@dsh-workbench/shared 1.1.14-beta.2 → 1.1.15

package/src/host/seam/run.ts

@@ -0,0 +1,478 @@
+import { now } from '../time.js';
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import type { DshShell } from '../../api/dsh.js';
+import { workbenchRoot } from '../data-root.js';
+import { shellKindOf } from '../shell-text.js';
+import { callOperatorOf, invocationOf, quotedArgvLine, quotedLineOf } from '../shell-render.js';
+import { runShell, type ShellResult } from '../shell.js';
+import { deniedPathOf, sandboxDeniedOf } from './denial.js';
+import { seamProductEnv } from './env.js';
+import { definedEnvOf, hostEnvOf } from './host-env.js';
+import type {
+  ChannelHandle,
+  ExecIntent,
+  OpenRequest,
+  ProcessChild,
+  ProcessHost,
+  SeamShellKind,
+  SeamTarget,
+  SpawnExit,
+  SpawnHandle,
+  SpawnRequest,
+} from './exec.js';
+import {
+  SeamError,
+  type DenialScope,
+  type SeamDenial,
+  type SeamFact,
+  type SeamMode,
+  type SeamPolicy,
+  type WriteIntent,
+} from './intent.js';
+import { denialScopeOf, narrowerMode, pathsPolicy, policyOf, productPolicy, seamModeOf, workspacePolicy } from './policy.js';
+import { createNodeProcessHost } from './process.js';
+
+export interface SeamRequest {
+  readonly command?: string | undefined;
+  readonly argv?: readonly string[] | undefined;
+  readonly shellKind?: SeamShellKind | undefined;
+  readonly intent: ExecIntent;
+  readonly session?: unknown;
+  readonly workdir?: string | undefined;
+  readonly timeoutMs?: number | undefined;
+  readonly maxBytes?: number | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly retry?: 'safe' | 'never' | undefined;
+  readonly bestEffort?: true | undefined;
+  readonly signal?: AbortSignal | undefined;
+}
+
+export interface SeamOutcome extends ShellResult {
+  readonly denial?: SeamDenial | undefined;
+}
+
+export interface Seam {
+  run(request: SeamRequest): Promise<SeamOutcome>;
+  spawn(request: SpawnRequest): SpawnHandle;
+  open(request: OpenRequest): ChannelHandle;
+  facts(): readonly SeamFact[];
+}
+
+export interface SeamPorts {
+  readonly shell: DshShell;
+  readonly runtimeRoot?: string | undefined;
+  readonly ceiling?: SeamMode | undefined;
+  readonly grantOf?: ((session: unknown) => SeamPolicy | undefined) | undefined;
+  readonly realHome?: string | undefined;
+  readonly allowHost?: boolean | undefined;
+  readonly processes?: ProcessHost | undefined;
+  readonly factLimit?: number | undefined;
+  readonly logger?: { warn?(message: string): void } | undefined;
+}
+
+const DENIAL_MARKER = /\[sandbox: file access denied under [a-z-]+ mode\]/i;
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+
+function scopeText(scope: DenialScope): string {
+  if (scope === 'product') return '工作台自己的目录';
+  if (scope === 'workspace') return '会话工作区';
+  if (scope === 'external') return '工作区之外的路径';
+  return '没认出来的路径';
+}
+
+function denialMessageOf(scope: DenialScope, path: string | undefined, output: string): string {
+  const where = path === undefined ? '' : `：${path}`;
+  const marker = DENIAL_MARKER.test(output) ? '' : '（输出里没有沙箱标记，按拒绝处理）';
+  const next =
+    scope === 'external'
+      ? '要写工作区外的路径得先让用户点头：把目标改到工作区，或让工具补上审批后再试'
+      : '这是工作台自己的声明问题，不是用户的配置问题：把命令、域与路径一起记下来交给维护者';
+  return `被沙箱挡住了（${scopeText(scope)}${where}）${marker}。${next}`;
+}
+
+function settle(result: ShellResult, denial?: SeamDenial): SeamOutcome {
+  return {
+    exitCode: result.exitCode,
+    timedOut: result.timedOut,
+    aborted: result.aborted,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    truncated: result.truncated,
+    stalled: result.stalled,
+    ...(denial === undefined ? {} : { denial }),
+  };
+}
+
+function targetOf(request: {
+  readonly command?: string | undefined;
+  readonly argv?: readonly string[] | undefined;
+}): SeamTarget {
+  const hasCommand = request.command !== undefined;
+  const hasArgv = request.argv !== undefined;
+  if (hasArgv && !hasCommand) {
+    const argv = request.argv ?? [];
+    if (argv.length === 0) throw new SeamError('scope-not-declared', 'argv 是空的：至少给一个可执行文件');
+    return { argv };
+  }
+  if (hasCommand && !hasArgv) return { line: request.command ?? '' };
+  throw new SeamError('scope-not-declared', '这条执行请求要么给 argv，要么给一条命令行，不能两个都给或都不给');
+}
+
+function displayOf(target: SeamTarget): string {
+  return 'argv' in target ? quotedArgvLine(target.argv) : target.line;
+}
+
+function targetInvocationOf(target: SeamTarget, shellKind: SeamShellKind | undefined): { file: string; args: readonly string[] } {
+  if ('argv' in target) {
+    const [file, ...args] = target.argv;
+    if (file === undefined) throw new SeamError('scope-not-declared', 'argv 是空的：至少给一个可执行文件');
+    return { file, args };
+  }
+  return invocationOf(shellKind ?? shellKindOf(), target.line);
+}
+
+function sandboxedLineOf(target: SeamTarget, shellKind: SeamShellKind | undefined): string {
+  const line = 'argv' in target ? quotedArgvLine(target.argv) : target.line;
+  if (shellKind === undefined) return callOperatorOf(shellKindOf(), line);
+  return callOperatorOf(shellKindOf(), quotedLineOf(invocationOf(shellKind, line)));
+}
+
+export function createSeam(ports: SeamPorts): Seam {
+  const runtimeRoot = ports.runtimeRoot ?? workbenchRoot();
+  const ceiling = ports.ceiling ?? seamModeOf(process.env['DSH_PERMISSION_MODE']);
+  const allowHost = ports.allowHost === true;
+  const processes = ports.processes ?? createNodeProcessHost();
+  const limit = ports.factLimit ?? 80;
+  const facts: SeamFact[] = [];
+
+  function record(fact: SeamFact): void {
+    facts.push(fact);
+    if (facts.length > limit) facts.splice(0, facts.length - limit);
+  }
+
+  function grantFor(session: unknown): SeamPolicy | undefined {
+    if (ports.grantOf === undefined || session === undefined || session === null) return undefined;
+    try {
+      return ports.grantOf(session);
+    } catch {
+      return undefined;
+    }
+  }
+
+  function requireHost(intent: ExecIntent): void {
+    if (intent.kind !== 'host') {
+      throw new SeamError('scope-not-declared', '这条调用要走宿主进程执行，但写入域不是 host');
+    }
+    if (!allowHost) throw new SeamError('scope-not-declared', '宿主域只给宿主侧接线开出来；模块与普通调用点拿不到');
+  }
+
+  async function attempt(request: SeamRequest, policy: SeamPolicy, line: string): Promise<ShellResult> {
+    return runShell(ports.shell, line, {
+      ...(request.workdir === undefined ? {} : { workdir: request.workdir }),
+      ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+      ...(request.signal === undefined ? {} : { signal: request.signal }),
+      env: { ...seamProductEnv({ runtimeRoot, realHome: ports.realHome }), ...definedEnvOf(request.env) },
+      sandboxPolicy: policy,
+    });
+  }
+
+  function healPolicyOf(intent: WriteIntent, scope: DenialScope, granted: SeamPolicy | undefined): SeamPolicy | undefined {
+    if (scope === 'product' && intent.kind !== 'product') return productPolicy(ceiling, runtimeRoot);
+    if (scope === 'workspace' && intent.kind === 'workspace') {
+      if (granted === undefined) return undefined;
+      try {
+        return workspacePolicy(ceiling, granted);
+      } catch {
+        return undefined;
+      }
+    }
+    return undefined;
+  }
+
+  async function runHost(request: SeamRequest, target: SeamTarget): Promise<ShellResult> {
+    const invocation = targetInvocationOf(target, request.shellKind);
+    const child = processes.spawn({
+      file: invocation.file,
+      args: invocation.args,
+      env: hostEnvOf(request.env),
+      ...(request.workdir === undefined ? {} : { cwd: request.workdir }),
+      detached: false,
+      stdio: 'pipe',
+      windowsHide: true,
+    });
+    const state = { stdout: '', stderr: '', truncated: false };
+    const append = (which: 'stdout' | 'stderr', chunk: string): void => {
+      const total = state.stdout.length + state.stderr.length;
+      const room = (request.maxBytes ?? DEFAULT_MAX_BYTES) - total;
+      if (room <= 0) {
+        state.truncated = true;
+        return;
+      }
+      const text = chunk.length > room ? chunk.slice(0, room) : chunk;
+      state[which] += text;
+      if (chunk.length > room) state.truncated = true;
+    };
+    child.stdout?.onData((chunk) => append('stdout', chunk));
+    child.stderr?.onData((chunk) => append('stderr', chunk));
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let timedOut = false;
+    if (request.timeoutMs !== undefined) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGKILL');
+      }, request.timeoutMs);
+    }
+    const exit = await new Promise<SpawnExit>((resolve) => {
+      child.onExit((event) => resolve(event));
+      child.onError((error) => {
+        state.stderr = `${state.stderr}${String(error)}`;
+        resolve({ code: null, signal: null });
+      });
+    });
+    if (timer !== undefined) clearTimeout(timer);
+    return {
+      exitCode: exit.code,
+      timedOut,
+      aborted: false,
+      stdout: state.stdout,
+      stderr: state.stderr,
+      truncated: state.truncated,
+      stalled: false,
+    };
+  }
+
+  function spawnHost(request: SpawnRequest): SpawnHandle {
+    const invocation = targetInvocationOf(request.target, undefined);
+    const logFile =
+      request.logFile ?? join(runtimeRoot, 'logs', `${request.label ?? 'spawn'}-${String(now())}.log`);
+    mkdirSync(dirname(logFile), { recursive: true });
+    const child = processes.spawn({
+      file: invocation.file,
+      args: invocation.args,
+      env: hostEnvOf(request.env),
+      ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
+      detached: true,
+      stdio: 'log',
+      logFile,
+      windowsHide: true,
+    });
+    child.unref();
+    record({
+      at: now(),
+      verb: 'spawn',
+      command: displayOf(request.target),
+      intent: 'host',
+      mode: 'host',
+      workspaceRoot: '',
+      exitCode: null,
+      timedOut: false,
+      stalled: false,
+    });
+    const display = displayOf(request.target);
+    const errorListeners = new Set<(error: Error) => void>();
+    const exitWaiters: Array<(event: SpawnExit) => void> = [];
+    let settled: SpawnExit | undefined;
+    let failure: Error | undefined;
+    const settleExit = (event: SpawnExit): void => {
+      if (settled !== undefined) return;
+      settled = event;
+      for (const waiter of exitWaiters.splice(0)) waiter(event);
+    };
+    child.onExit((event) => settleExit(event));
+    child.onError((error) => {
+      failure = error;
+      settleExit({ code: null, signal: null });
+      if (errorListeners.size === 0) {
+        ports.logger?.warn?.(`[dsh-workbench] 起进程没跑起来（${display}）：${String(error)}`);
+        return;
+      }
+      for (const listener of errorListeners) listener(error);
+    });
+    return {
+      pid: child.pid,
+      logFile,
+      exit: () =>
+        settled === undefined
+          ? new Promise<SpawnExit>((resolve) => exitWaiters.push(resolve))
+          : Promise.resolve(settled),
+      onError(listener) {
+        if (failure !== undefined) {
+          listener(failure);
+          return () => {};
+        }
+        errorListeners.add(listener);
+        return () => errorListeners.delete(listener);
+      },
+      kill: (signal) => child.kill(signal ?? 'SIGTERM'),
+    };
+  }
+
+  function openHost(request: OpenRequest): ChannelHandle {
+    const invocation = targetInvocationOf(request.target, undefined);
+    const child: ProcessChild = processes.spawn({
+      file: invocation.file,
+      args: invocation.args,
+      env: hostEnvOf(request.env),
+      ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
+      detached: false,
+      stdio: 'pipe',
+      windowsHide: true,
+    });
+    record({
+      at: now(),
+      verb: 'open',
+      command: displayOf(request.target),
+      intent: 'host',
+      mode: 'host',
+      workspaceRoot: '',
+      exitCode: null,
+      timedOut: false,
+      stalled: false,
+    });
+    const display = displayOf(request.target);
+    const errorListeners = new Set<(error: Error) => void>();
+    const exitListeners = new Set<(event: SpawnExit) => void>();
+    let failure: Error | undefined;
+    let settled: SpawnExit | undefined;
+    const settleExit = (event: SpawnExit): void => {
+      if (settled !== undefined) return;
+      settled = event;
+      for (const listener of exitListeners) listener(event);
+    };
+    child.onExit((event) => settleExit(event));
+    child.onError((error) => {
+      failure = error;
+      settleExit({ code: null, signal: null });
+      if (errorListeners.size === 0) {
+        ports.logger?.warn?.(`[dsh-workbench] 双向通道起不来（${display}）：${String(error)}`);
+        return;
+      }
+      for (const listener of errorListeners) listener(error);
+    });
+    return {
+      pid: child.pid,
+      write: (chunk) => child.stdin?.write(chunk),
+      onData(listener) {
+        const offOut = child.stdout?.onData(listener) ?? (() => {});
+        const offErr = child.stderr?.onData(listener) ?? (() => {});
+        return () => {
+          offOut();
+          offErr();
+        };
+      },
+      onExit(listener) {
+        if (settled !== undefined) {
+          listener(settled);
+          return () => {};
+        }
+        exitListeners.add(listener);
+        return () => exitListeners.delete(listener);
+      },
+      onError(listener) {
+        if (failure !== undefined) {
+          listener(failure);
+          return () => {};
+        }
+        errorListeners.add(listener);
+        return () => errorListeners.delete(listener);
+      },
+      kill: (signal) => child.kill(signal ?? 'SIGTERM'),
+    };
+  }
+
+  return {
+    async run(request: SeamRequest): Promise<SeamOutcome> {
+      const target = targetOf(request);
+      if (request.intent.kind === 'host') {
+        requireHost(request.intent);
+        const started = now();
+        const result = await runHost(request, target);
+        record({
+          at: started,
+          verb: 'run',
+          command: displayOf(target),
+          intent: 'host',
+          mode: 'host',
+          workspaceRoot: '',
+          exitCode: result.exitCode,
+          timedOut: result.timedOut,
+          stalled: result.stalled,
+        });
+        return settle(result);
+      }
+      const granted = grantFor(request.session);
+      const intent: WriteIntent = request.intent;
+      const policy = policyOf(intent, ceiling, runtimeRoot, granted);
+      const line = sandboxedLineOf(target, request.shellKind);
+      let result = await attempt(request, policy, line);
+      if (!sandboxDeniedOf(result.sandbox)) {
+        record({
+          at: now(),
+          verb: 'run',
+          command: line,
+          intent: intent.kind,
+          mode: policy.mode,
+          workspaceRoot: policy.workspaceRoot,
+          exitCode: result.exitCode,
+          timedOut: result.timedOut,
+          stalled: result.stalled,
+        });
+        return settle(result);
+      }
+
+      const path = deniedPathOf(result.stderr, result.stdout);
+      const scope = denialScopeOf(path, policy, runtimeRoot, granted);
+      const healedPolicy = request.retry === 'safe' ? healPolicyOf(intent, scope, granted) : undefined;
+      let healed = false;
+      if (healedPolicy !== undefined) {
+        const retried = await attempt(request, healedPolicy, line).catch(() => undefined);
+        if (retried !== undefined && !sandboxDeniedOf(retried.sandbox)) {
+          result = retried;
+          healed = true;
+        }
+      }
+      const denial: SeamDenial = {
+        ...(path === undefined ? {} : { path }),
+        scope,
+        ...(healed ? { healed: true } : {}),
+      };
+      record({
+        at: now(),
+        verb: 'run',
+        command: line,
+        intent: intent.kind,
+        mode: policy.mode,
+        workspaceRoot: policy.workspaceRoot,
+        exitCode: result.exitCode,
+        timedOut: result.timedOut,
+        stalled: result.stalled,
+        denial,
+      });
+      if (healed) return settle(result, denial);
+      if (request.bestEffort === true) {
+        ports.logger?.warn?.(`[dsh-workbench] ${denialMessageOf(scope, path, `${result.stderr}\n${result.stdout}`)}`);
+        return settle(result, denial);
+      }
+      throw new SeamError('sandbox-denied', denialMessageOf(scope, path, `${result.stderr}\n${result.stdout}`), {
+        ...(path === undefined ? {} : { path }),
+        scope,
+      });
+    },
+    spawn(request: SpawnRequest): SpawnHandle {
+      requireHost(request.intent);
+      return spawnHost(request);
+    },
+    open(request: OpenRequest): ChannelHandle {
+      requireHost(request.intent);
+      return openHost(request);
+    },
+    facts: () => facts,
+  };
+}
+
+export function sealedPolicyOf(policy: SeamPolicy, ceiling: SeamMode): SeamPolicy {
+  return { mode: narrowerMode(ceiling, policy.mode), workspaceRoot: policy.workspaceRoot };
+}
+
+export { pathsPolicy, policyOf, productPolicy, workspacePolicy };

package/src/host/seam/service.ts

@@ -0,0 +1,8 @@
+import type { DshHostContext } from '../../api/dsh.js';
+import type { Seam } from './run.js';
+
+export const WORKBENCH_SEAM = 'workbenchSeam';
+
+export function seamOf(ctx: DshHostContext): Seam | undefined {
+  return ctx.get<Seam>(WORKBENCH_SEAM, false);
+}

package/src/host/seam/unit-seam.ts

@@ -0,0 +1,62 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { seamUnitEnv } from './env.js';
+import { SeamError, type UnitSeamRequest, type UnitWriteScope } from './intent.js';
+import type { Seam, SeamOutcome } from './run.js';
+
+export interface UnitSeamPorts {
+  readonly seam: Seam;
+  readonly unit: string;
+  readonly runtimeRoot: string;
+  readonly declared?: readonly UnitWriteScope[] | undefined;
+  readonly realHome?: string | undefined;
+}
+
+export interface UnitSeam {
+  run(request: UnitSeamRequest): Promise<SeamOutcome>;
+}
+
+export function unitDataRoot(runtimeRoot: string, unit: string): string {
+  return join(runtimeRoot, 'units', unit);
+}
+
+export function createUnitSeam(ports: UnitSeamPorts): UnitSeam {
+  const unitRoot = unitDataRoot(ports.runtimeRoot, ports.unit);
+  mkdirSync(unitRoot, { recursive: true });
+  const declared = new Set<UnitWriteScope>(ports.declared ?? []);
+  const env = seamUnitEnv({ runtimeRoot: ports.runtimeRoot, unitRoot, realHome: ports.realHome });
+
+  return {
+    async run(request: UnitSeamRequest): Promise<SeamOutcome> {
+      const common = {
+        command: request.command,
+        ...(request.workdir === undefined ? {} : { workdir: request.workdir }),
+        ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+        ...(request.signal === undefined ? {} : { signal: request.signal }),
+        ...(request.retry === undefined ? {} : { retry: request.retry }),
+      };
+      if (request.scope === 'unit') {
+        return ports.seam.run({
+          ...common,
+          intent: { kind: 'product' },
+          env: { ...env, ...(request.env ?? {}) },
+        });
+      }
+      if (!declared.has('workspace')) {
+        throw new SeamError(
+          'scope-not-declared',
+          `${ports.unit} 的清单没有声明 host.writes 里的 workspace：要写当前工作区，先在清单里声明`,
+        );
+      }
+      if (request.session === undefined || request.session === null) {
+        throw new SeamError('workspace-unknown', `${ports.unit} 请求写工作区，但这次调用没有会话`);
+      }
+      return ports.seam.run({
+        ...common,
+        intent: { kind: 'workspace' },
+        session: request.session,
+        env: { ...(request.env ?? {}) },
+      });
+    },
+  };
+}

package/src/host/shell-render.ts

@@ -0,0 +1,28 @@
+import type { ShellKind } from './shell-text.js';
+import { quoteShellArgFor } from './shell-text.js';
+
+export interface ShellInvocation {
+  readonly file: string;
+  readonly args: readonly string[];
+}
+
+const QUOTED_HEAD = /^\s*['"]/;
+
+export function callOperatorOf(kind: ShellKind, script: string): string {
+  if (kind !== 'pwsh' || !QUOTED_HEAD.test(script)) return script;
+  return `& ${script}`;
+}
+
+export function invocationOf(kind: ShellKind, script: string): ShellInvocation {
+  return kind === 'pwsh'
+    ? { file: 'pwsh', args: ['-NoProfile', '-NonInteractive', '-Command', callOperatorOf('pwsh', script)] }
+    : { file: 'bash', args: ['-c', script] };
+}
+
+export function quotedArgvLine(argv: readonly string[], platform: NodeJS.Platform = process.platform): string {
+  return argv.map((one) => quoteShellArgFor(one, platform)).join(' ');
+}
+
+export function quotedLineOf(invocation: ShellInvocation, platform: NodeJS.Platform = process.platform): string {
+  return quotedArgvLine([invocation.file, ...invocation.args], platform);
+}

package/src/host/shell.ts

@@ -1,6 +1,13 @@
 import type { DshShell } from '../api/dsh.js';
 import { GIT_TIMEOUT_MS } from '../config/constants.js';
 
+export interface ShellSandboxFacts {
+  readonly mode?: string | undefined;
+  readonly denied?: boolean | undefined;
+  readonly enforcement?: string | undefined;
+  readonly runnerFailed?: boolean | undefined;
+}
+
 export interface ShellResult {
   readonly exitCode: number | null;
   readonly timedOut: boolean;
@@ -9,6 +16,7 @@ export interface ShellResult {
   readonly stderr: string;
   readonly truncated: boolean;
   readonly stalled: boolean;
+  readonly sandbox?: ShellSandboxFacts | undefined;
 }
 
 const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
@@ -39,6 +47,11 @@ async function settleWithin<T>(work: Promise<T>, limitMs: number): Promise<T | n
   }
 }
 
+export interface DshShellSandboxPolicy {
+  readonly mode: 'read-only' | 'workspace-write' | 'danger-full-access';
+  readonly workspaceRoot: string;
+}
+
 export async function runShell(
   shell: DshShell,
   command: string,
@@ -47,9 +60,10 @@ export async function runShell(
     timeoutMs?: number;
     signal?: AbortSignal;
     env?: Readonly<Record<string, string>>;
+    sandboxPolicy?: DshShellSandboxPolicy | undefined;
   } = {},
 ): Promise<ShellResult> {
-  const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal, env } = options;
+  const { workdir, timeoutMs = GIT_TIMEOUT_MS, signal, env, sandboxPolicy } = options;
 
   const spec = shell.resolve({
     command,
@@ -59,6 +73,7 @@ export async function runShell(
     stdoutMaxBytes: DEFAULT_MAX_BYTES,
     ...(signal === undefined ? {} : { signal }),
     ...(env === undefined ? {} : { env }),
+    ...(sandboxPolicy === undefined ? {} : { sandboxPolicy }),
   });
 
   const settled = await settleWithin(
@@ -73,6 +88,7 @@ export async function runShell(
         stderr: result.stderr.text,
         truncated: result.stdout.truncated || result.stderr.truncated,
         stalled: false,
+        ...(result.sandbox === undefined ? {} : { sandbox: result.sandbox }),
       };
     })(),
     timeoutMs + GUARD_SLACK_MS,

package/src/host/time.ts

@@ -20,3 +20,19 @@ export function clockOf(value: string | number | Date): string {
 export function epochOf(value: string | number | Date): number {
   return dayjs(value).valueOf();
 }
+
+/**
+ * 当前时间（毫秒）。宿主里要「现在几点」只走这里，测试可以点住 `Date.now`。
+ * @returns 毫秒时间戳。
+ */
+export function now(): number {
+  return Date.now();
+}
+
+/**
+ * 当前时间的 ISO 字符串。
+ * @returns `new Date().toISOString()` 的等价物。
+ */
+export function nowIso(): string {
+  return new Date(now()).toISOString();
+}

package/src/host/value-handoff.ts

@@ -1,3 +1,4 @@
+import { now as clockNow } from './time.js';
 import { HANDOFF_TTL_MS } from '../config/constants.js';
 
 export interface HandoffEntry {
@@ -24,10 +25,10 @@ export function createValueHandoff(options: { ttlMs?: number } = {}): ValueHando
   const held = new Map<string, HandoffValue>();
 
   return {
-    hand(entry, value, now = Date.now()) {
+    hand(entry, value, now: number = clockNow()) {
       held.set(handoffId(entry), { value, at: now });
     },
-    take(entry, now = Date.now()) {
+    take(entry, now: number = clockNow()) {
       const id = handoffId(entry);
       const hit = held.get(id);
       if (hit === undefined) return undefined;