docs: rebalance prose cleanup and add trimming skill

packages/sandbox/sandbox-local/tests/bwrap.e2e.ts

@@ -9,8 +9,11 @@ import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import { bwrapProfileArgs, LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 
 /**
- * Keyless bwrap integration proof for the backend: the real `bwrap` confining real processes
- * through `confine()` + a direct spawn of the returned argv.
+ * Keyless backend integration through `confine()` and a real bwrap process. With no rung forced,
+ * a passing probe must select the first rung. Tests assert world effects, wrap shape, and that the
+ * kernel denial matches the advertised dialect; consumer coverage lives in dsh-bash-sandbox.
+ * Skips when bwrap or user namespaces are unavailable. HOME-based workspaces avoid bwrap's
+ * ephemeral `/tmp`, so workspace-write actually proves the workspace-root rebind.
  */
 
 const probe = spawnSync('bwrap', [...bwrapProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' })

packages/sandbox/sandbox-local/tests/landlock.e2e.ts

@@ -10,10 +10,10 @@ import { launcherPath } from 'node-addon-landlock-run'
 import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
 
 /**
- * Keyless Landlock integration proof for the backend: the real npm-distributed `landlock-run`
- * launcher (`node-addon-landlock-run`) confining real processes through `confine()` + a direct
- * spawn of the returned argv, with the bwrap rung forced off so the ladder lands on the
- * launcher.
+ * Keyless backend integration through `confine()` and the registry `landlock-run` launcher, with
+ * bwrap forced off. Tests assert real world effects; consumer coverage lives in dsh-bash-sandbox.
+ * Skips when the platform package or enforcing kernel is unavailable. HOME-based workspaces avoid
+ * Landlock's wholesale `/tmp` grant, so workspace-write proves the workspace-root grant itself.
  */
 
 const probe = spawnSync(launcherPath(), ['--probe'], { timeout: 5_000, encoding: 'utf8' })

packages/sandbox/sandbox-local/tests/local.spec.ts

@@ -259,7 +259,8 @@ describe('the platform chains', () => {
   })
 
   it('a rogue cached runner tag throws via the exhaustiveness guard (closed union)', async () => {
-    // A rogue runner tag must hit assertNever.
+    // Only a cast can create this rogue closed-union tag. It must hit `assertNever`, ensuring a new
+    // runner cannot silently use another runner's wrap or denial dialect.
     const { sandbox } = await setup()
     ;(sandbox as unknown as { selectedRunner: unknown }).selectedRunner = { runner: 'chroot', enforcement: 'full' }
     expect(() => sandbox.confine(['true'], RO)).toThrow('unreachable variant')

packages/sandbox/sandbox-local/tests/packed-install.e2e.ts

@@ -6,7 +6,16 @@ import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 
-/** Keyless packed-tarball smoke in an external plain-Node consumer. */
+/**
+ * Keyless publish-path rehearsal. It packs the package and workspace peers, installs those exact
+ * tarballs in an external plain-Node consumer, and lets npm resolve the registry Landlock launcher
+ * plus its platform package. No tsx, path mapping, or workspace resolution can hide missing files,
+ * dependency errors, or lost executable modes.
+ *
+ * The installed launcher must match the host architecture, remain executable, and either confine a
+ * real process with bwrap disabled or fail closed on a non-enforcing kernel. Skips off Linux or
+ * before `pnpm run build`; launcher byte provenance belongs to its upstream release pipeline.
+ */
 
 const packageDir = fileURLToPath(new URL('..', import.meta.url))
 const repoRoot = fileURLToPath(new URL('../../../..', import.meta.url))
@@ -59,7 +68,8 @@ describe.skipIf(!packable)('sandbox-local: packed-tarball distribution (publish-
       tarballs.push(lines[lines.length - 1] as string)
     }
 
-    // Install packed tarballs in a plain ESM consumer, including optional platform dependencies.
+    // Peer ranges resolve to the tarballs; Cordis is pinned to their peer range. Do not omit optional
+    // dependencies because the launcher selects its OS/CPU package through one.
     writeFileSync(join(consumerDir, 'package.json'), JSON.stringify({ name: 'dsh-packed-consumer', private: true, type: 'module' }))
     const install = spawnSync('npm', ['install', '--no-audit', '--no-fund', ...tarballs, 'cordis@4.0.0-rc.6'], {
       cwd: consumerDir,

packages/sandbox/sandbox-local/tests/seatbelt.e2e.ts

@@ -9,9 +9,11 @@ import type { SandboxPolicy } from '@deepseek-ai/dsh-sandbox'
 import { LocalSandboxProvider, seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local'
 
 /**
- * Keyless Seatbelt integration proof for the backend: the real macOS `sandbox-exec` confining
- * real processes through `confine()` + a direct spawn of the returned argv, with the Linux
- * rungs forced off so the ladder lands on Seatbelt.
+ * Keyless backend integration through `confine()` and a real macOS Seatbelt process, with Linux
+ * rungs forced off. Tests assert world effects and that the kernel denial matches the advertised
+ * dialect; consumer coverage lives in dsh-bash-sandbox. Skips off macOS or when the profile probe
+ * fails. HOME-based workspaces avoid Seatbelt's wholesale temp-directory grants, so
+ * workspace-write proves the workspace-root grant itself.
  */
 
 const probe = spawnSync('sandbox-exec', [...seatbeltProfileArgs({ mode: 'read-only', workspaceRoot: '/' }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' })