@dsh-workbench/shared 1.1.3 → 1.1.5

package/src/host/install-failure.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import {
+  classifyInstallFailure,
+  installFailureOf,
+  installTargets,
+  installWriteProblem,
+} from './install-failure.js';
+
+const CURRENT = { uid: 502, gid: 20 };
+
+describe('installTargets（从我们自己的安装命令里挑出写点）', () => {
+  it('挑出 --prefix 与原样带空格的路径', () => {
+    expect(installTargets(`npm i --prefix '/Users/a b/x' foo@1 --cache /tmp/c`)).toEqual([
+      '/Users/a b/x',
+      '/tmp/c',
+    ]);
+  });
+
+  it('没有 --prefix / --cache 就没有写点', () => {
+    expect(installTargets('npm ls --json --depth 0')).toEqual([]);
+  });
+});
+
+describe('classifyInstallFailure', () => {
+  it('EPERM / EACCES 都算权限', () => {
+    expect(classifyInstallFailure('npm error code EACCES')).toBe('permission');
+    expect(classifyInstallFailure('npm error syscall open errno EPERM')).toBe('permission');
+  });
+
+  it('ENOSPC 是盘满', () => {
+    expect(classifyInstallFailure('ENOSPC: no space left on device')).toBe('disk-full');
+  });
+
+  it('认不出来就说认不出来', () => {
+    expect(classifyInstallFailure('')).toBe('unknown');
+  });
+});
+
+describe('installFailureOf（从现场推到修法）', () => {
+  it('属主不是当前账号 → chown 回自己', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 1,
+      output: 'EACCES: permission denied',
+      path: '/x',
+      owner: { uid: 0, gid: 0 },
+      mode: '755',
+      writable: false,
+      current: CURRENT,
+    });
+
+    expect(failure.kind).toBe('permission');
+    expect(failure.fix).toEqual({ kind: 'chown', path: '/x', uid: 502, gid: 20 });
+  });
+
+  it('属主是自己、只是没写位 → chmod，不给 sudo', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 1,
+      output: 'EACCES: permission denied',
+      path: '/x',
+      owner: { uid: 502, gid: 20 },
+      mode: '555',
+      writable: false,
+      current: CURRENT,
+    });
+
+    expect(failure.fix).toEqual({ kind: 'chmod', path: '/x' });
+  });
+
+  it('属主是自己、明明可写却报 EPERM → 是被别的沙箱拦的，不给一条没用的 sudo', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 1,
+      output: 'EPERM: operation not permitted',
+      path: '/x',
+      owner: { uid: 502, gid: 20 },
+      mode: '755',
+      writable: true,
+      current: CURRENT,
+    });
+
+    expect(failure.kind).toBe('sandbox');
+    expect(failure.fix).toEqual({ kind: 'handoff' });
+  });
+
+  it('盘满 → 指向精简的命令，而不是 chown', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 1,
+      output: 'ENOSPC: no space left on device',
+      path: '/x',
+      current: CURRENT,
+    });
+
+    expect(failure.kind).toBe('disk-full');
+    expect(failure.fix).toEqual({ kind: 'space', path: '/x' });
+  });
+
+  it('认不出来 → 交接给 agent，不硬猜修法', () => {
+    const failure = installFailureOf({
+      command: 'npm i --prefix /x foo@1',
+      exitCode: 255,
+      output: 'something odd',
+      current: CURRENT,
+    });
+
+    expect(failure.kind).toBe('unknown');
+    expect(failure.fix).toEqual({ kind: 'handoff' });
+  });
+});
+
+describe('installWriteProblem（装之前先看一眼，省得白跑）', () => {
+  it('只盯安装动词：npm ls 这种读命令不拦', () => {
+    expect(installWriteProblem({ command: 'npm ls --prefix /x foo --json' })).toBeUndefined();
+  });
+
+  it('目录不存在 → 退到最近的祖先，不报假问题', () => {
+    expect(installWriteProblem({ command: `npm i --prefix ${process.cwd()}/definitely-missing-dir foo` })).toBeUndefined();
+  });
+});

package/src/host/install-failure.ts

@@ -0,0 +1,198 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { InstallFailure, InstallFailureKind } from '../contract/command.js';
+
+const TARGET_FLAGS = ['--prefix', '--cache', '--dir', '--store-dir'];
+
+const INSTALL_VERBS = /^\s*npm\s+(i|install|add)\b/;
+
+const NPM_PATH = /^npm (?:error|ERR!) path (.+)$/m;
+
+export interface DirFacts {
+  readonly mode: string;
+  readonly owner: { readonly uid: number; readonly gid: number };
+  readonly writable: boolean;
+}
+
+export function commandTokens(command: string): string[] {
+  const tokens: string[] = [];
+  const token = /'([^']*)'|"([^"]*)"|(\S+)/g;
+  for (let match = token.exec(command); match !== null; match = token.exec(command)) {
+    tokens.push(match[1] ?? match[2] ?? match[3] ?? '');
+  }
+  return tokens;
+}
+
+export function installTargets(command: string): string[] {
+  const tokens = commandTokens(command);
+  const targets: string[] = [];
+  for (let index = 0; index < tokens.length - 1; index += 1) {
+    if (TARGET_FLAGS.includes(tokens[index] ?? '')) targets.push(tokens[index + 1] ?? '');
+  }
+  return targets.filter((target) => target !== '');
+}
+
+export function failurePathIn(output: string): string | undefined {
+  const path = NPM_PATH.exec(output)?.[1]?.trim();
+  return path === undefined || path === '' ? undefined : path;
+}
+
+export function nearestDir(path: string): string | undefined {
+  let at = path;
+  for (;;) {
+    const here = (): boolean => {
+      try {
+        return statSync(at).isDirectory();
+      } catch {
+        return false;
+      }
+    };
+    if (here()) return at;
+    const up = dirname(at);
+    if (up === at) return undefined;
+    at = up;
+  }
+}
+
+export type WriteState = 'ok' | 'denied' | 'unknown';
+
+export function writeStateOf(dir: string): WriteState {
+  try {
+    accessSync(dir, constants.W_OK);
+    return 'ok';
+  } catch (error) {
+    return (error as { code?: string }).code === 'EACCES' ? 'denied' : 'unknown';
+  }
+}
+
+export function dirFacts(dir: string): DirFacts | undefined {
+  try {
+    const stats = statSync(dir);
+    return {
+      mode: (stats.mode & 0o777).toString(8),
+      owner: { uid: stats.uid, gid: stats.gid },
+      writable: writeStateOf(dir) === 'ok',
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function currentUser(): { readonly uid: number; readonly gid: number } {
+  return { uid: process.getuid?.() ?? -1, gid: process.getgid?.() ?? -1 };
+}
+
+export function classifyInstallFailure(output: string): InstallFailureKind {
+  const text = output.toLowerCase();
+  if (/enospc|no space left/.test(text)) return 'disk-full';
+  if (/eacces|eperm|permission denied|operation not permitted|access is denied/.test(text)) return 'permission';
+  return 'unknown';
+}
+
+export interface InstallFailureFacts {
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly output: string;
+  readonly kind?: InstallFailureKind | undefined;
+  readonly path?: string | undefined;
+  readonly mode?: string | undefined;
+  readonly owner?: { readonly uid: number; readonly gid: number } | undefined;
+  readonly writable?: boolean | undefined;
+  readonly current: { readonly uid: number; readonly gid: number };
+}
+
+export function installFailureOf(facts: InstallFailureFacts): InstallFailure {
+  const kind = facts.kind ?? classifyInstallFailure(facts.output);
+  const path = facts.path;
+  const base = {
+    command: facts.command,
+    exitCode: facts.exitCode,
+    output: facts.output,
+    ...(path === undefined ? {} : { path }),
+    ...(facts.mode === undefined ? {} : { mode: facts.mode }),
+    ...(facts.owner === undefined ? {} : { owner: facts.owner }),
+    current: facts.current,
+  };
+  if (kind === 'disk-full') {
+    return { ...base, kind, fix: path === undefined ? { kind: 'handoff' } : { kind: 'space', path } };
+  }
+  if (kind === 'permission' && path !== undefined) {
+    const owner = facts.owner;
+    if (owner !== undefined && owner.uid !== facts.current.uid && facts.current.uid >= 0) {
+      return { ...base, kind, fix: { kind: 'chown', path, uid: facts.current.uid, gid: facts.current.gid } };
+    }
+    if (facts.writable === false) {
+      return { ...base, kind, fix: { kind: 'chmod', path } };
+    }
+    if (facts.writable === true) {
+      return { ...base, kind: 'sandbox', fix: { kind: 'handoff' } };
+    }
+  }
+  return { ...base, kind, fix: { kind: 'handoff' } };
+}
+
+export function diagnoseInstallFailure(input: {
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly output: string;
+  readonly fallback?: string | undefined;
+}): InstallFailure {
+  const current = currentUser();
+  const candidates = [
+    failurePathIn(input.output),
+    ...installTargets(input.command),
+    input.fallback,
+  ].filter((path): path is string => path !== undefined && path !== '');
+  for (const candidate of candidates) {
+    const dir = nearestDir(candidate);
+    if (dir === undefined) continue;
+    const facts = dirFacts(dir);
+    if (facts === undefined) continue;
+    return installFailureOf({
+      command: input.command,
+      exitCode: input.exitCode,
+      output: input.output,
+      path: dir,
+      mode: facts.mode,
+      owner: facts.owner,
+      writable: facts.writable,
+      current,
+    });
+  }
+  return installFailureOf({
+    command: input.command,
+    exitCode: input.exitCode,
+    output: input.output,
+    current,
+  });
+}
+
+export function installWriteProblem(input: {
+  readonly command: string;
+  readonly fallback?: string | undefined;
+}): InstallFailure | undefined {
+  if (!INSTALL_VERBS.test(input.command)) return undefined;
+  const current = currentUser();
+  const candidates = [...installTargets(input.command), input.fallback].filter(
+    (path): path is string => path !== undefined && path !== '',
+  );
+  for (const candidate of candidates) {
+    const dir = nearestDir(candidate);
+    if (dir === undefined) continue;
+    if (writeStateOf(dir) !== 'denied') continue;
+    const facts = dirFacts(dir);
+    if (facts === undefined) continue;
+    return installFailureOf({
+      command: input.command,
+      exitCode: null,
+      output: '',
+      kind: 'permission',
+      path: dir,
+      mode: facts.mode,
+      owner: facts.owner,
+      writable: facts.writable,
+      current,
+    });
+  }
+  return undefined;
+}

package/src/host/installed-sources.test.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import {
+  forgetPackageSource,
+  installedSourcesFile,
+  packageSourceOf,
+  readInstalledSources,
+  rememberPackageSource,
+} from './installed-sources.js';
+
+const dirs: string[] = [];
+
+function profile(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wb-sources-'));
+  dirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+describe('按包记安装来源（检查更新只认这一份）', () => {
+  it('写一条再读回来：版本与源都在，文件是临时名换过去的', () => {
+    const dir = profile();
+    rememberPackageSource(dir, '@a/mod', { version: '0.3.1', registry: 'https://r1.example/' });
+
+    expect(packageSourceOf(dir, '@a/mod')).toEqual({ version: '0.3.1', registry: 'https://r1.example/' });
+    expect(fs.existsSync(`${installedSourcesFile(dir)}.tmp`)).toBe(false);
+  });
+
+  it('★ 同一个 scope 的两个包可以各记各的源（.npmrc 做不到这件事）', () => {
+    const dir = profile();
+    rememberPackageSource(dir, '@x/a', { version: '1.0.0', registry: 'https://r1.example/' });
+    rememberPackageSource(dir, '@x/b', { version: '2.0.0', registry: 'https://r2.example/' });
+
+    expect(packageSourceOf(dir, '@x/a')?.registry).toBe('https://r1.example/');
+    expect(packageSourceOf(dir, '@x/b')?.registry).toBe('https://r2.example/');
+    expect(readInstalledSources(dir)).toHaveProperty('@x/a');
+  });
+
+  it('再装一次同一个包 → 覆盖成这次记录的版本与源', () => {
+    const dir = profile();
+    rememberPackageSource(dir, '@x/a', { version: '1.0.0', registry: 'https://r1.example/' });
+    rememberPackageSource(dir, '@x/a', { version: '1.1.0', registry: 'https://r2.example/' });
+
+    expect(packageSourceOf(dir, '@x/a')).toEqual({ version: '1.1.0', registry: 'https://r2.example/' });
+  });
+
+  it('卸载后删掉；没有这条时也不写空文件', () => {
+    const dir = profile();
+    rememberPackageSource(dir, '@x/a', { version: '1.0.0', registry: 'https://r1.example/' });
+    forgetPackageSource(dir, '@x/a');
+
+    expect(packageSourceOf(dir, '@x/a')).toBeUndefined();
+    const before = fs.readFileSync(installedSourcesFile(dir), 'utf8');
+    forgetPackageSource(dir, '@x/never');
+    expect(fs.readFileSync(installedSourcesFile(dir), 'utf8')).toBe(before);
+  });
+
+  it('文件坏了 / 没有 / profile 不认识 → 一律当没有记录，不抛', () => {
+    const dir = profile();
+    fs.writeFileSync(installedSourcesFile(dir), '{ 坏的 json', 'utf8');
+    expect(readInstalledSources(dir)).toEqual({});
+    expect(packageSourceOf(dir, '@x/a')).toBeUndefined();
+    expect(readInstalledSources(null)).toEqual({});
+  });
+
+  it('空包名 / 空源 / 空版本不落盘（别把没问到的写进去当事实）', () => {
+    const dir = profile();
+    rememberPackageSource(dir, ' ', { version: '1.0.0', registry: 'https://r1.example/' });
+    rememberPackageSource(dir, '@x/a', { version: '', registry: 'https://r1.example/' });
+    rememberPackageSource(dir, '@x/b', { version: '1.0.0', registry: ' ' });
+
+    expect(readInstalledSources(dir)).toEqual({});
+    expect(fs.existsSync(installedSourcesFile(dir))).toBe(false);
+  });
+});

package/src/host/installed-sources.ts

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface InstalledSource {
+  readonly version: string;
+  readonly registry: string;
+}
+
+export type InstalledSourceMap = Readonly<Record<string, InstalledSource>>;
+
+const FILE_NAME = '.dsh-workbench-sources.json';
+const FILE_VERSION = 1;
+
+function asRecord(value: unknown): Readonly<Record<string, unknown>> | undefined {
+  return typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : undefined;
+}
+
+function asText(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function installedSourcesFile(profileDir: string): string {
+  return path.join(profileDir, FILE_NAME);
+}
+
+export function readInstalledSources(profileDir: string | null): InstalledSourceMap {
+  if (profileDir === null) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(installedSourcesFile(profileDir), 'utf8'));
+  } catch {
+    return {};
+  }
+  const packages = asRecord(asRecord(parsed)?.packages);
+  if (packages === undefined) return {};
+  const found: Record<string, InstalledSource> = {};
+  for (const [pkg, value] of Object.entries(packages)) {
+    const record = asRecord(value);
+    if (record === undefined) continue;
+    const version = asText(record.version);
+    const registry = asText(record.registry);
+    if (pkg === '' || version === '' || registry === '') continue;
+    found[pkg] = { version, registry };
+  }
+  return found;
+}
+
+export function packageSourceOf(profileDir: string | null, pkg: string): InstalledSource | undefined {
+  return readInstalledSources(profileDir)[pkg];
+}
+
+function writeInstalledSources(profileDir: string, sources: InstalledSourceMap): void {
+  const file = installedSourcesFile(profileDir);
+  const temp = `${file}.tmp`;
+  const text = `${JSON.stringify({ version: FILE_VERSION, packages: sources }, null, 2)}\n`;
+  fs.writeFileSync(temp, text, { mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+
+export function rememberPackageSource(profileDir: string, pkg: string, source: InstalledSource): void {
+  const trimmed = pkg.trim();
+  if (trimmed === '' || source.version.trim() === '' || source.registry.trim() === '') return;
+  const all = { ...readInstalledSources(profileDir) };
+  all[trimmed] = { version: source.version.trim(), registry: source.registry.trim() };
+  writeInstalledSources(profileDir, all);
+}
+
+export function forgetPackageSource(profileDir: string, pkg: string): void {
+  const all = { ...readInstalledSources(profileDir) };
+  if (all[pkg] === undefined) return;
+  delete all[pkg];
+  writeInstalledSources(profileDir, all);
+}

package/src/host/lib-install.ts

@@ -1,4 +1,5 @@
-import type { LibNeed, SupplySource } from '../contract/needs.js';
+import type { BinNeed, LibNeed, SupplySource } from '../contract/needs.js';
+import type { HostOs } from '../contract/protocol/platform.js';
 import { npmRegistryOf } from './plugin-source.js';
 import { quoteShellArg } from './shell-text.js';
 import { libsPrefix, npmCacheDir } from './paths.js';
@@ -9,10 +10,45 @@ export function libInstallCommand(options: {
   readonly need: LibNeed;
   readonly source: NpmSource;
   readonly version?: string | undefined;
+  readonly env?: NodeJS.ProcessEnv | undefined;
 }): string {
   const { need, source, version } = options;
-  const registry = npmRegistryOf(source, process.env);
+  const registry = npmRegistryOf(source, options.env ?? process.env);
   const spec = version ?? need.version ?? 'latest';
   const registryFlag = registry.ok ? ` --registry ${quoteShellArg(registry.value)}` : '';
   return `npm i --prefix ${quoteShellArg(libsPrefix())} ${quoteShellArg(`${need.name}@${spec}`)}${registryFlag} --cache ${quoteShellArg(npmCacheDir())}`;
 }
+
+/**
+ * 这个 bin 在这台机器上怎么装：作者写了 `install` 且平台对得上才给出那条命令。
+ * `command` 原样照抄；`npm` 装进隔离运行时的共用依赖前缀（那份包里的 bin 会自动上 PATH）。
+ * @param need 一条 bin 需要。
+ * @param os 宿主平台（由平台适配器给出）。
+ * @param env 取 registry 环境变量的地方。
+ * @returns 一条能直接粘进终端的命令；没声明或平台不对就是 undefined。
+ */
+export function binInstallCommand(
+  need: BinNeed,
+  os: HostOs,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const install = need.install;
+  if (install === undefined) return undefined;
+  if (install.platforms !== undefined && !install.platforms.includes(os)) return undefined;
+  if (install.kind === 'command') {
+    const line = install.line.trim();
+    return line === '' ? undefined : line;
+  }
+  const packageName = install.package.trim();
+  if (packageName === '') return undefined;
+  return libInstallCommand({
+    need: { kind: 'lib', name: packageName, purpose: need.purpose },
+    source: {
+      kind: 'npm',
+      package: packageName,
+      ...(install.registryEnv === undefined ? {} : { registryEnv: install.registryEnv }),
+      ...(install.registryDefault === undefined ? {} : { registryDefault: install.registryDefault }),
+    },
+    env,
+  });
+}

package/src/host/paths.test.ts

@@ -0,0 +1,26 @@
+import { delimiter } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { ensureLibsBinOnPath, libsBinDir, npmCacheDir } from './paths.js';
+
+describe('隔离运行时的路径', () => {
+  it('共用依赖的 bin 目录就在 libs 下面', () => {
+    expect(libsBinDir().endsWith('/opencli/libs/node_modules/.bin')).toBe(true);
+    expect(npmCacheDir().endsWith('/opencli/npm-cache')).toBe(true);
+  });
+
+  it('★ 把 bin 目录前插一次；再插不会重复（PATH 不许越跑越长）', () => {
+    const env = { PATH: `/usr/bin${delimiter}/bin` };
+    const dir = libsBinDir();
+
+    expect(ensureLibsBinOnPath(env)).toBe(true);
+    expect(env.PATH).toBe(`${dir}${delimiter}/usr/bin${delimiter}/bin`);
+    expect(ensureLibsBinOnPath(env)).toBe(false);
+    expect(env.PATH.split(delimiter).filter((one) => one === dir)).toHaveLength(1);
+  });
+
+  it('PATH 是空的也能插', () => {
+    const env: NodeJS.ProcessEnv = {};
+    expect(ensureLibsBinOnPath(env)).toBe(true);
+    expect(env.PATH).toBe(libsBinDir());
+  });
+});

package/src/host/paths.ts

@@ -1,3 +1,4 @@
+import { delimiter } from 'node:path';
 import { workbenchRoot } from './data-root.js';
 
 export function isolatedRoot(): string {
@@ -35,3 +36,20 @@ export function vendorPeerLink(): { readonly dir: string; readonly parent: strin
 export function npmCacheDir(): string {
   return `${isolatedRoot()}/npm-cache`;
 }
+
+export function libsBinDir(): string {
+  return `${libsPrefix()}/node_modules/.bin`;
+}
+
+/**
+ * 把隔离运行时的共用依赖 bin 目录放到 PATH 最前面（可执行文件都从这儿找）。
+ * @param env 改哪份环境（默认当前进程）。
+ * @returns 真的插进去了就 `true`；已经在里面就 `false`。
+ */
+export function ensureLibsBinOnPath(env: NodeJS.ProcessEnv = process.env): boolean {
+  const dir = libsBinDir();
+  const parts = (env.PATH ?? '').split(delimiter).filter((one) => one !== '');
+  if (parts.includes(dir)) return false;
+  env.PATH = [dir, ...parts].join(delimiter);
+  return true;
+}

package/src/host/runtime-links.test.ts

@@ -0,0 +1,31 @@
+import { existsSync, mkdirSync, mkdtempSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ensureLibsOpencliPeer } from './runtime-links.js';
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe('ensureLibsOpencliPeer', () => {
+  it('★ 运行时那份 opencli 在 → 链到 libs，libs 里的命令才 import 得到它', () => {
+    const root = mkdtempSync(join(tmpdir(), 'wb-peer-'));
+    vi.stubEnv('DSH_WORKBENCH_HOME', root);
+    mkdirSync(join(root, 'opencli/toolchain/node_modules/@jackwener/opencli'), { recursive: true });
+
+    expect(ensureLibsOpencliPeer()).toBe(true);
+    const link = join(root, 'opencli/libs/node_modules/@jackwener/opencli');
+    expect(existsSync(link)).toBe(true);
+    expect(realpathSync(link)).toContain('toolchain/node_modules/@jackwener/opencli');
+    expect(ensureLibsOpencliPeer()).toBe(false);
+  });
+
+  it('运行时还没装 opencli → 不建空链接（等它装好再说）', () => {
+    const root = mkdtempSync(join(tmpdir(), 'wb-peer-'));
+    vi.stubEnv('DSH_WORKBENCH_HOME', root);
+
+    expect(ensureLibsOpencliPeer()).toBe(false);
+    expect(existsSync(join(root, 'opencli/libs/node_modules/@jackwener/opencli'))).toBe(false);
+  });
+});

package/src/host/runtime-links.ts

@@ -0,0 +1,23 @@
+import { existsSync, mkdirSync, symlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { OPENCLI_NPM_PACKAGE, libsPrefix, toolchainOpencliDir } from './paths.js';
+
+/**
+ * 让共用依赖也能 import opencli：把隔离运行时里那份 opencli 链接到 libs 的 node_modules。
+ * 跑在 libs 里的命令（比如 opencli-workflow 带的 gitops）会按包名找 @jackwener/opencli，
+ * 找不到就起不来 —— 它不在 libs 的依赖里，是运行时提供的那一份。
+ * @returns 这次真的建了链接就 `true`；已经有了、或运行时那份还没装，就是 `false`。
+ */
+export function ensureLibsOpencliPeer(): boolean {
+  const link = `${libsPrefix()}/node_modules/${OPENCLI_NPM_PACKAGE}`;
+  if (existsSync(link)) return false;
+  const target = toolchainOpencliDir();
+  if (!existsSync(target)) return false;
+  try {
+    mkdirSync(dirname(link), { recursive: true });
+    symlinkSync(target, link);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/host/tool-approval.ts

@@ -1,3 +1,7 @@
+export { APPROVAL_NOTE_ARG } from '../contract/approval.js';
+
+import { APPROVAL_NOTE_ARG } from '../contract/approval.js';
+
 export type AskDecision =
   | {
       readonly kind: 'ask';
@@ -16,8 +20,6 @@ export interface ApprovalDetail {
 
 export type ApprovalFacts = ApprovalDetail | { readonly blocked: string };
 
-export const APPROVAL_NOTE_ARG = 'approval_note';
-
 export const APPROVAL_NOTE_LIMIT = 40;
 
 export const APPROVAL_DETAIL_LIMIT = 20;
@@ -77,7 +79,8 @@ export interface ApprovalCall {
 
 /**
  * 套件对一次写调用给出的判定：`read` 只是看看、`allow` 会写但本套件不问、`deny` 这一次根本跑不成
- * （连问都不该问，`reason` 原样交给 agent）、`ask` 要用户点头（`question` 接在明细后，`fallback` 是没明细时的整句）。
+ * （连问都不该问，`reason` 原样交给 agent）、`ask` 要用户点头（`question` 接在明细后，`fallback` 是没明细时的整句；
+ * `noteInDetail` 为真表示套件把 agent 的附注画在自己的详情座里，标题只留动作、不再追加）。
  */
 export type ApprovalVerdict =
   | { readonly kind: 'read' }
@@ -91,6 +94,7 @@ export type ApprovalVerdict =
       readonly reason: string;
       readonly question: ApprovalDetail;
       readonly fallback: ApprovalDetail;
+      readonly noteInDetail?: boolean;
     };
 
 export type ApprovalPolicy = (call: ApprovalCall) => ApprovalVerdict | undefined;
@@ -168,9 +172,12 @@ export async function approvalFor(
 
   if (context.skipAsk === true) return undefined;
 
+  const note =
+    context.declaredNote === true && verdict.noteInDetail !== true ? approvalNoteOf(call) : undefined;
+
   return {
     kind: 'ask',
     reason: verdict.reason,
-    displayReason: compose(facts, verdict, context.declaredNote === true ? approvalNoteOf(call) : undefined),
+    displayReason: compose(facts, verdict, note),
   };
 }