@dsh-workbench/shared 1.1.14-beta.1 → 1.1.14

package/src/host/package-route.ts

@@ -1,4 +1,5 @@
-import type { DshShell } from '../api/dsh.js';
+import { now } from './time.js';
+import type { Seam } from './seam/run.js';
 import { VERSION_CHECK_TTL_MS } from '../config/constants.js';
 import { dshMarkersOf, splitNpmSpec, verdictOf, type PackageVerdict } from './package-kind.js';
 import { withPackageDir } from './package-content.js';
@@ -30,7 +31,7 @@ export interface PackageRouter {
 
 interface RouteOptions {
   readonly spec: string;
-  readonly shell?: DshShell | undefined;
+  readonly seam?: Seam | undefined;
   readonly registry?: string | undefined;
   readonly force?: boolean;
 }
@@ -38,7 +39,7 @@ interface RouteOptions {
 export interface PackageRouterOptions {
   readonly manifestFile: string;
   readonly cacheDir?: string | undefined;
-  readonly dshLookup?: ((options: { shell: DshShell; name: string; registry: string }) => Promise<{ readable: boolean; raw: unknown }>) | undefined;
+  readonly dshLookup?: ((options: { seam: Seam; name: string; registry: string }) => Promise<{ readable: boolean; raw: unknown }>) | undefined;
 }
 
 export function createPackageRouter(options: PackageRouterOptions): PackageRouter {
@@ -64,30 +65,30 @@ async function routeOf(
 
   const ref = splitNpmSpec(routeOptions.spec);
   if (ref === undefined) return undefined;
-  const shell = routeOptions.shell;
+  const seam = routeOptions.seam;
   const registry = routeOptions.registry;
-  if (shell === undefined || registry === undefined) return undefined;
+  if (seam === undefined || registry === undefined) return undefined;
 
   const key = `${registry}|${routeOptions.spec}`;
   const hit = cache.get(key);
-  if (routeOptions.force !== true && hit !== undefined && Date.now() - hit.at < VERSION_CHECK_TTL_MS) {
+  if (routeOptions.force !== true && hit !== undefined && now() - hit.at < VERSION_CHECK_TTL_MS) {
     return hit.route ?? undefined;
   }
 
   const found =
     options.dshLookup === undefined
       ? { readable: false, raw: undefined }
-      : await options.dshLookup({ shell, name: routeOptions.spec, registry });
+      : await options.dshLookup({ seam, name: routeOptions.spec, registry });
   let route: PackageRoute | undefined;
   if (found.readable && dshMarkersOf(found.raw)) {
     route = { kind: 'dsh-bundle' };
   } else {
     const verdict = await withPackageDir(
-      { shell, spec: routeOptions.spec, registry, ...(options.cacheDir === undefined ? {} : { cacheDir: options.cacheDir }) },
+      { seam, spec: routeOptions.spec, registry, ...(options.cacheDir === undefined ? {} : { cacheDir: options.cacheDir }) },
       (dir) => verdictOf(dir, options.manifestFile),
     );
     route = verdict === undefined ? undefined : routeOfVerdict(verdict, ref.name);
   }
-  cache.set(key, { at: Date.now(), route: route ?? null });
+  cache.set(key, { at: now(), route: route ?? null });
   return route;
 }

package/src/host/panel-state.ts

@@ -1,3 +1,4 @@
+import { now } from './time.js';
 /**
  * 一张面板卡片取数走到哪一步：`idle` 还没取、`loading` 取着、`ready` 拿到了、`error` 失败了。
  */
@@ -188,7 +189,7 @@ export function parseCrashReport(payload: unknown): PanelParse<PanelCrashReport>
   if (workspace === '') return { ok: false, message: 'workspace 不能是空的' };
   if (unit === '') return { ok: false, message: 'unit 不能是空的' };
   if (reason === '') return { ok: false, message: 'reason 不能是空的（没有原因的崩溃没法查）' };
-  return { ok: true, value: { workspace, unit, reason, at: atOf(record['at']) ?? Date.now() } };
+  return { ok: true, value: { workspace, unit, reason, at: atOf(record['at']) ?? now() } };
 }
 
 /**

package/src/host/patch-blocks.ts

@@ -0,0 +1,67 @@
+export interface PatchBlock {
+  readonly key: string;
+  readonly id: string;
+  readonly insert: boolean;
+  readonly body: string;
+  readonly names: readonly string[];
+}
+
+export interface SpannedBlock extends PatchBlock {
+  readonly from: number;
+  readonly to: number;
+}
+
+const ID_LINE = /^- id:[ \t]*"?([^"\s#]+)/;
+const INSERT_LINE = /^- insert:[ \t]*$/;
+const NESTED_ID = /^[ \t]+-[ \t]*id:[ \t]*"?([^"\s#]+)/;
+const NAME_LINE = /^[ \t]*-?[ \t]*name:[ \t]*['"]?([^'"\s#]+)/;
+
+function trimmedTail(lines: readonly string[]): readonly string[] {
+  let end = lines.length;
+  while (end > 0 && (lines[end - 1] ?? '').trim() === '') end -= 1;
+  return lines.slice(0, end);
+}
+
+function matched(text: string, pattern: RegExp): string | undefined {
+  const found = pattern.exec(text);
+  return found === null ? undefined : found[1];
+}
+
+function blockOf(body: string, index: number): PatchBlock {
+  const lines = body.split('\n');
+  const first = lines[0] ?? '';
+  const id = matched(first, ID_LINE);
+  const nested = lines.flatMap((line) => {
+    const one = matched(line, NESTED_ID);
+    return one === undefined ? [] : [one];
+  });
+  const insert = id === undefined && INSERT_LINE.test(first);
+  const label = id ?? nested.join(', ');
+  const key = id !== undefined ? `id:${id}` : insert ? `insert:${nested.join(', ')}` : `block:${String(index)}`;
+  const names = lines.flatMap((line) => {
+    const one = matched(line, NAME_LINE);
+    return one === undefined ? [] : [one];
+  });
+  return { key, id: label === '' ? key : label, insert, body, names };
+}
+
+export function spannedBlocks(text: string): SpannedBlock[] {
+  const lines = text.split('\n');
+  const starts: number[] = [];
+  lines.forEach((line, index) => {
+    if (/^- /.test(line) || line === '-') starts.push(index);
+  });
+  const blocks: SpannedBlock[] = [];
+  for (let i = 0; i < starts.length; i += 1) {
+    const from = starts[i] ?? 0;
+    const to = i + 1 < starts.length ? (starts[i + 1] ?? lines.length) : lines.length;
+    const body = trimmedTail(lines.slice(from, to)).join('\n');
+    if (body.trim() === '') continue;
+    blocks.push({ ...blockOf(body, blocks.length), from, to });
+  }
+  return blocks;
+}
+
+export function patchBlocks(text: string): PatchBlock[] {
+  return spannedBlocks(text).map(({ from: _from, to: _to, ...block }) => block);
+}

package/src/host/patch.ts

@@ -1,93 +1,9 @@
-import { renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { writeTextFile } from './fs-write.js';
+import { patchBlocks, type PatchBlock } from './patch-blocks.js';
 
-export interface PatchBlock {
-  readonly key: string;
-  readonly id: string;
-  readonly insert: boolean;
-  readonly body: string;
-  readonly names: readonly string[];
-}
-
-interface SpannedBlock extends PatchBlock {
-  readonly from: number;
-  readonly to: number;
-}
-
-const ID_LINE = /^- id:[ \t]*"?([^"\s#]+)/;
-const INSERT_LINE = /^- insert:[ \t]*$/;
-const NESTED_ID = /^[ \t]+-[ \t]*id:[ \t]*"?([^"\s#]+)/;
-const NAME_LINE = /^[ \t]*-?[ \t]*name:[ \t]*['"]?([^'"\s#]+)/;
-
-function trimmedTail(lines: readonly string[]): readonly string[] {
-  let end = lines.length;
-  while (end > 0 && (lines[end - 1] ?? '').trim() === '') end -= 1;
-  return lines.slice(0, end);
-}
-
-function matched(text: string, pattern: RegExp): string | undefined {
-  const found = pattern.exec(text);
-  return found === null ? undefined : found[1];
-}
-
-function blockOf(body: string, index: number): PatchBlock {
-  const lines = body.split('\n');
-  const first = lines[0] ?? '';
-  const id = matched(first, ID_LINE);
-  const nested = lines.flatMap((line) => {
-    const one = matched(line, NESTED_ID);
-    return one === undefined ? [] : [one];
-  });
-  const insert = id === undefined && INSERT_LINE.test(first);
-  const label = id ?? nested.join(', ');
-  const key = id !== undefined ? `id:${id}` : insert ? `insert:${nested.join(', ')}` : `block:${String(index)}`;
-  const names = lines.flatMap((line) => {
-    const one = matched(line, NAME_LINE);
-    return one === undefined ? [] : [one];
-  });
-  return { key, id: label === '' ? key : label, insert, body, names };
-}
-
-function spannedBlocks(text: string): SpannedBlock[] {
-  const lines = text.split('\n');
-  const starts: number[] = [];
-  lines.forEach((line, index) => {
-    if (/^- /.test(line) || line === '-') starts.push(index);
-  });
-  const blocks: SpannedBlock[] = [];
-  for (let i = 0; i < starts.length; i += 1) {
-    const from = starts[i] ?? 0;
-    const to = i + 1 < starts.length ? (starts[i + 1] ?? lines.length) : lines.length;
-    const body = trimmedTail(lines.slice(from, to)).join('\n');
-    if (body.trim() === '') continue;
-    blocks.push({ ...blockOf(body, blocks.length), from, to });
-  }
-  return blocks;
-}
-
-export function patchBlocks(text: string): PatchBlock[] {
-  return spannedBlocks(text).map(({ from: _from, to: _to, ...block }) => block);
-}
-
-function patchMode(path: string): number {
-  try {
-    return statSync(path).mode & 0o777;
-  } catch {
-    return 0o644;
-  }
-}
+export { patchBlocks, type PatchBlock };
 
+/** 把 patch 文本写回原文件：原子写，保留已有权限位（新文件 0644）。 */
 export function writePatchFile(path: string, text: string): void {
-  const mode = patchMode(path);
-  const tmp = `${path}.wb-sync-${String(process.pid)}`;
-  writeFileSync(tmp, text, { mode });
-  try {
-    renameSync(tmp, path);
-  } catch (error) {
-    try {
-      unlinkSync(tmp);
-    } catch {
-      throw error;
-    }
-    throw error;
-  }
+  writeTextFile(path, text, { mode: 'keep' });
 }

package/src/host/port-types.ts

@@ -1,4 +1,5 @@
-import type { DshHostContext, DshShell } from '../api/dsh.js';
+import type { DshHostContext } from '../api/dsh.js';
+import type { Seam } from './seam/run.js';
 import type { RuntimeCapabilities, RuntimeProfile } from '../contract/capabilities.js';
 import type { PluginPackageKind } from '../contract/protocol/bundle-install.js';
 import type { LibNeed, SupplySource } from '../contract/needs.js';
@@ -57,14 +58,14 @@ export interface SupplyPluginInstallOptions {
 }
 
 export interface SupplyLatestOptions {
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly name: string;
   readonly registry: string;
   readonly force?: boolean;
 }
 
 export interface SupplyMissingPartsOptions {
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly name: string;
   readonly registry: string;
   readonly version: string;
@@ -72,7 +73,7 @@ export interface SupplyMissingPartsOptions {
 }
 
 export interface SupplyProbeReleaseOptions {
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly package: string;
   readonly registry?: string | undefined;
   readonly force?: boolean;
@@ -116,7 +117,7 @@ export interface ModulePort {
   declarationGaps(dir: string | null): readonly { readonly pkg: string }[] | undefined;
   moduleDeclarationOf(dir: string | null, pkg: string): unknown;
   registryDeclarationOf(options: {
-    readonly shell: DshShell;
+    readonly seam: Seam;
     readonly name: string;
     readonly registry: string;
     readonly force?: boolean;
@@ -126,7 +127,7 @@ export interface ModulePort {
   refusalReason(): string;
   packageRouteOf(options: {
     readonly spec: string;
-    readonly shell?: DshShell | undefined;
+    readonly seam?: Seam | undefined;
     readonly registry?: string | undefined;
     readonly force?: boolean;
   }): Promise<SupplyPackageRoute | undefined>;
@@ -140,7 +141,7 @@ export interface SupplyPort extends EnvSupplyPort, ModulePort {
 }
 
 export interface ProbeUnitsOptions {
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly runtimeCommands: Readonly<Record<string, string>>;
   readonly units: readonly NeedProbeInput[];
   readonly force?: boolean;
@@ -149,7 +150,7 @@ export interface ProbeUnitsOptions {
 export interface ProbePreflightInput {
   readonly routes: RouteTable;
   readonly ctx: DshHostContext;
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly runtimeCommands: Readonly<Record<string, string>>;
   readonly runtimeCapabilities: RuntimeCapabilities;
   readonly runtimeCheck?: (() => Promise<RuntimeCheck>) | undefined;
@@ -195,7 +196,6 @@ export interface RuntimePort {
   runners(ctx: DshHostContext, data: DataReader): Readonly<Record<string, LibRunner>>;
   health(ctx: DshHostContext): Readonly<Record<string, RuntimeStatus>>;
   seed(ctx: DshHostContext, options: RuntimeSeedOptions): void;
-  warnUnwritableRoot(ctx: DshHostContext): void;
 }
 
 export interface PluginDeclarationSource {

package/src/host/profile-registries.ts

@@ -2,6 +2,7 @@ import type { RegistryEntry, RegistryNotebook } from './adapter-types.js';
 import { normalizeRegistry, sameRegistry, scopeOf } from './adapter-types.js';
 import fs from 'node:fs';
 import path from 'node:path';
+import { writeTextFile } from './fs-write.js';
 export const REGISTRY_MARKER =
   '# dsh-workbench 写的：这一行的包只在这个源上（dsh 卸载没有源参数，pnpm 得问得到）';
 
@@ -93,9 +94,7 @@ function readNpmrc(file: string): string {
 }
 
 function writeNpmrc(file: string, text: string): void {
-  const temp = `${file}.dsh-workbench.tmp`;
-  fs.writeFileSync(temp, text, { mode: 0o600 });
-  fs.renameSync(temp, file);
+  writeTextFile(file, text, { mode: 0o600 });
 }
 
 export function createRegistryNotebook(dir: string | null): RegistryNotebook {

package/src/host/registry-declaration.ts

@@ -1,5 +1,6 @@
-import type { DshShell } from '../api/dsh.js';
-import { runShell } from './shell.js';
+import { now } from './time.js';
+import { productWrite } from './seam/intent.js';
+import type { Seam } from './seam/run.js';
 import { quoteShellArg } from './shell-text.js';
 import { parseJsonLoose } from '../lib/text.js';
 import { VERSION_CHECK_TIMEOUT_MS, VERSION_CHECK_TTL_MS } from '../config/constants.js';
@@ -19,7 +20,7 @@ export interface RegistryLookup {
 }
 
 interface RegistryDshOptions {
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly name: string;
   readonly registry?: string | undefined;
   readonly force?: boolean;
@@ -42,29 +43,33 @@ export function createRegistryLookup(): RegistryLookup {
 }
 
 async function dshOf(cache: Map<string, { at: number; raw: unknown }>, options: {
-  shell: DshShell;
+  seam: Seam;
   name: string;
   registry?: string | undefined;
   force?: boolean;
   cacheDir?: string | undefined;
 }): Promise<RegistryDshLookup> {
-  const { shell, name, registry, force = false, cacheDir } = options;
+  const { seam, name, registry, force = false, cacheDir } = options;
   const key = `${registry ?? ''}|${name}`;
   const hit = cache.get(key);
-  if (!force && hit !== undefined && Date.now() - hit.at < VERSION_CHECK_TTL_MS) {
+  if (!force && hit !== undefined && now() - hit.at < VERSION_CHECK_TTL_MS) {
     return { readable: true, raw: hit.raw };
   }
 
   const at = registry === undefined ? '' : ` --registry ${quoteShellArg(registry)}`;
   const cached = cacheDir === undefined ? '' : ` --cache ${quoteShellArg(cacheDir)}`;
-  const result = await runShell(
-    shell,
-    `npm view ${quoteShellArg(name)} dsh --json${at}${cached}`,
-    { timeoutMs: VERSION_CHECK_TIMEOUT_MS },
-  ).catch(() => undefined);
+  const result = await seam
+    .run({
+      command: `npm view ${quoteShellArg(name)} dsh --json${at}${cached}`,
+      intent: productWrite(),
+      retry: 'safe',
+      timeoutMs: VERSION_CHECK_TIMEOUT_MS,
+      bestEffort: true,
+    })
+    .catch(() => undefined);
   const parsed = result?.exitCode === 0 ? parseJsonLoose(result.stdout) : undefined;
   if (parsed === undefined) return { readable: false, raw: undefined };
-  cache.set(key, { at: Date.now(), raw: parsed });
+  cache.set(key, { at: now(), raw: parsed });
   return { readable: true, raw: parsed };
 }
 

package/src/host/release-probe.ts

@@ -1,4 +1,6 @@
-import type { DshShell } from '../api/dsh.js';
+import { now } from './time.js';
+import type { Seam } from './seam/run.js';
+import { productWrite } from './seam/intent.js';
 import type { PluginRelease } from '../contract/unit.js';
 
 import { RELEASE_PACKAGES } from './release-packages.generated.js';
@@ -6,7 +8,6 @@ import { VERSION_CHECK_TIMEOUT_MS, VERSION_CHECK_TTL_MS } from '../config/consta
 import { isValidVersion } from './version.js';
 import { parseJsonLoose } from '../lib/text.js';
 import { quoteShellArg } from './shell-text.js';
-import { runShell } from './shell.js';
 
 function cacheFlag(cacheDir: string | undefined): string {
   return cacheDir === undefined ? '' : ` --cache ${quoteShellArg(cacheDir)}`;
@@ -61,7 +62,7 @@ export function createReleaseProbe(): ReleaseProbe {
 }
 
 interface LatestVersionOptions {
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly name: string;
   readonly registry: string;
   readonly force?: boolean;
@@ -69,7 +70,7 @@ interface LatestVersionOptions {
 }
 
 interface MissingPartsOptions {
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly name: string;
   readonly registry: string;
   readonly version: string;
@@ -78,7 +79,7 @@ interface MissingPartsOptions {
 }
 
 interface ProbeReleaseOptions {
-  readonly shell: DshShell;
+  readonly seam: Seam;
   readonly package: string;
   readonly registry?: string | undefined;
   readonly force?: boolean;
@@ -88,25 +89,29 @@ interface ProbeReleaseOptions {
 }
 
 async function latestVersionOf(latestCache: Map<string, CacheEntry>, options: {
-  shell: DshShell;
+  seam: Seam;
   name: string;
   registry: string;
   force?: boolean;
   cacheDir?: string | undefined;
 }): Promise<string | undefined> {
-  const { shell, name, registry, force = false, cacheDir } = options;
+  const { seam, name, registry, force = false, cacheDir } = options;
   const key = `${registry}|${name}`;
   const hit = latestCache.get(key);
-  if (!force && hit !== undefined && Date.now() - hit.at < VERSION_CHECK_TTL_MS)
+  if (!force && hit !== undefined && now() - hit.at < VERSION_CHECK_TTL_MS)
     return hit.value;
 
-  const result = await runShell(
-    shell,
-    `npm view ${quoteShellArg(name)} version --registry ${quoteShellArg(registry)}${cacheFlag(cacheDir)}`,
-    { timeoutMs: VERSION_CHECK_TIMEOUT_MS },
-  ).catch(() => undefined);
+  const result = await seam
+    .run({
+      command: `npm view ${quoteShellArg(name)} version --registry ${quoteShellArg(registry)}${cacheFlag(cacheDir)}`,
+      intent: productWrite(),
+      retry: 'safe',
+      timeoutMs: VERSION_CHECK_TIMEOUT_MS,
+      bestEffort: true,
+    })
+    .catch(() => undefined);
   const read = result?.exitCode === 0 ? parseVersion(result.stdout) : undefined;
-  latestCache.set(key, { at: Date.now(), value: read });
+  latestCache.set(key, { at: now(), value: read });
   return read;
 }
 
@@ -119,26 +124,30 @@ interface ExistsEntry {
 async function versionExists(
   existsCache: Map<string, ExistsEntry>,
   options: {
-  shell: DshShell;
+  seam: Seam;
   name: string;
   version: string;
   registry: string;
   force?: boolean;
   cacheDir?: string | undefined;
 }): Promise<boolean> {
-  const { shell, name, version, registry, force = false, cacheDir } = options;
+  const { seam, name, version, registry, force = false, cacheDir } = options;
   const key = `${registry}|${name}@${version}`;
   const hit = existsCache.get(key);
-  if (!force && hit !== undefined && (hit.value || Date.now() - hit.at < VERSION_CHECK_TTL_MS))
+  if (!force && hit !== undefined && (hit.value || now() - hit.at < VERSION_CHECK_TTL_MS))
     return hit.value;
 
-  const result = await runShell(
-    shell,
-    `npm view ${quoteShellArg(`${name}@${version}`)} version --registry ${quoteShellArg(registry)}${cacheFlag(cacheDir)}`,
-    { timeoutMs: VERSION_CHECK_TIMEOUT_MS },
-  ).catch(() => undefined);
+  const result = await seam
+    .run({
+      command: `npm view ${quoteShellArg(`${name}@${version}`)} version --registry ${quoteShellArg(registry)}${cacheFlag(cacheDir)}`,
+      intent: productWrite(),
+      retry: 'safe',
+      timeoutMs: VERSION_CHECK_TIMEOUT_MS,
+      bestEffort: true,
+    })
+    .catch(() => undefined);
   const value = result?.exitCode === 0 && parseVersion(result.stdout) !== undefined;
-  existsCache.set(key, { at: Date.now(), value });
+  existsCache.set(key, { at: now(), value });
   return value;
 }
 
@@ -146,18 +155,18 @@ async function missingPartsOf(
   latestCache: Map<string, CacheEntry>,
   existsCache: Map<string, ExistsEntry>,
   options: {
-  shell: DshShell;
+  seam: Seam;
   name: string;
   registry: string;
   version: string;
   force?: boolean;
   cacheDir?: string | undefined;
 }): Promise<readonly string[]> {
-  const { shell, name, registry, version, force = false, cacheDir } = options;
+  const { seam, name, registry, version, force = false, cacheDir } = options;
   const checked = await Promise.all(
     RELEASE_PACKAGES.filter((part) => part !== name).map(async (part) => ({
       part,
-      present: await versionExists(existsCache, { shell, name: part, version, registry, force, cacheDir }),
+      present: await versionExists(existsCache, { seam, name: part, version, registry, force, cacheDir }),
     })),
   );
   return checked.filter((entry) => !entry.present).map((entry) => entry.part);
@@ -166,7 +175,7 @@ async function missingPartsOf(
 async function probeOf(
   latestCache: Map<string, CacheEntry>,
   options: {
-  shell: DshShell;
+  seam: Seam;
   package: string;
   registry?: string | undefined;
   force?: boolean;
@@ -174,14 +183,18 @@ async function probeOf(
   cacheDir?: string | undefined;
   prefix?: string | undefined;
 }): Promise<PluginRelease | undefined> {
-  const { shell, package: pkg, registry, force = false, check = true, cacheDir, prefix } = options;
+  const { seam, package: pkg, registry, force = false, check = true, cacheDir, prefix } = options;
   if (pkg === "") return undefined;
 
-  const ledger = await runShell(
-    shell,
-    `npm ls --prefix ${quoteShellArg(prefix ?? '')} ${quoteShellArg(pkg)} --json --depth=0${cacheFlag(cacheDir)}`,
-    { timeoutMs: VERSION_CHECK_TIMEOUT_MS },
-  ).catch(() => undefined);
+  const ledger = await seam
+    .run({
+      command: `npm ls --prefix ${quoteShellArg(prefix ?? '')} ${quoteShellArg(pkg)} --json --depth=0${cacheFlag(cacheDir)}`,
+      intent: productWrite(),
+      retry: 'safe',
+      timeoutMs: VERSION_CHECK_TIMEOUT_MS,
+      bestEffort: true,
+    })
+    .catch(() => undefined);
   const installed =
     ledger === undefined ? undefined : parseLedgerVersion(ledger.stdout, pkg);
   if (installed === undefined) return undefined;
@@ -193,7 +206,7 @@ async function probeOf(
   const latest =
     source === undefined || !check
       ? undefined
-      : await latestVersionOf(latestCache, { shell, name: pkg, registry: source, force, cacheDir });
+      : await latestVersionOf(latestCache, { seam, name: pkg, registry: source, force, cacheDir });
 
   return {
     installed,

package/src/host/seam/denial.ts

@@ -0,0 +1,26 @@
+const PATTERNS: readonly RegExp[] = [
+  /npm (?:error|ERR!) path (.+)$/m,
+  /(?:EPERM|EACCES):[^,\n]*, (?:open|unlink|mkdir|scandir|rename|access|stat|lstat|read|write|copyfile|rmdir|opendir|utimes|chmod|chown) '([^']+)'/i,
+  /(?:Operation not permitted|Permission denied)[^\n]*?'([^']+)'/i,
+  /fatal: could not create work tree dir '([^']+)'/i,
+  /mkdir: cannot create directory '([^']+)'/i,
+  /cannot (?:create|mkdir) (?:directory )?'([^']+)'/i,
+  /(?:Operation not permitted|Permission denied):\s*([^\s'\n]+)/i,
+];
+
+function firstMatch(text: string): string | undefined {
+  for (const pattern of PATTERNS) {
+    const found = pattern.exec(text);
+    const value = found?.[1]?.trim();
+    if (value !== undefined && value !== '') return value;
+  }
+  return undefined;
+}
+
+export function deniedPathOf(stderr: string, stdout = ''): string | undefined {
+  return firstMatch(stderr) ?? firstMatch(stdout);
+}
+
+export function sandboxDeniedOf(facts: { readonly denied?: boolean | undefined } | undefined): boolean {
+  return facts?.denied === true;
+}

package/src/host/seam/env.ts

@@ -0,0 +1,23 @@
+import { productEnvOf, unitEnvOf, type ProductEnvInput, type UnitEnvInput } from '../env-policy.js';
+
+export type SeamEnvInput = ProductEnvInput;
+
+export type SeamUnitEnvInput = UnitEnvInput;
+
+/**
+ * 产品域（运行时根）的受控 env：隔离 HOME、npm/pnpm 缓存钉在运行时根、真 npmrc/gitconfig 只读指过去。
+ * @param input 运行时根、可选的 HOME 与真实用户目录。
+ * @returns 产品域 env。
+ */
+export function seamProductEnv(input: SeamEnvInput): Record<string, string> {
+  return productEnvOf(input);
+}
+
+/**
+ * 模块单元的受控 env：HOME 与 npm/pnpm 目录钉到单元数据目录。
+ * @param input 运行时根、单元数据目录、可选的 TRUE 用户目录。
+ * @returns 单元 env。
+ */
+export function seamUnitEnv(input: SeamUnitEnvInput): Record<string, string> {
+  return unitEnvOf(input);
+}