Merge master into worktree/semantic-session-checkpoints

2026-07-22 21:49:24 +08:00
parent 568cdb6a39 2e9afef556
commit 3679b4d829
277 changed files with 8425 additions and 2215 deletions
--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -55,13 +55,18 @@
    "@cordisjs/plugin-timer": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-policy": "workspace:^",
+    "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
    "@deepseek-ai/dsh-goal": "workspace:^",
    "@deepseek-ai/dsh-goal-session": "workspace:^",
-    "@deepseek-ai/dsh-fs-local": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-paths": "workspace:^",
    "@deepseek-ai/dsh-llm-retry": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
    "@deepseek-ai/dsh-scope": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-session-title": "workspace:^",
@@ -70,11 +75,13 @@
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tasks": "workspace:^",
    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
    "@deepseek-ai/dsh-tool-goal": "workspace:^",
    "@deepseek-ai/dsh-tool-skill": "workspace:^",
    "@deepseek-ai/dsh-tool-tasks": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
    "@deepseek-ai/dsh-workspace-context": "workspace:^",
+    "node-addon-landlock-run": "0.0.0-test.0",
    "cordis": "^4.0.0-rc.7"
  },
  "dependencies": {
--- a/packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts
+++ b/packages/examples/agent-spine-demo/tests/multi-project-sandbox.e2e.ts
@@ -0,0 +1,243 @@
+import { spawnSync } from 'node:child_process'
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { SandboxBashExecutor } from '@deepseek-ai/dsh-bash-sandbox'
+import * as FsPolicy from '@deepseek-ai/dsh-fs-policy'
+import SandboxedFileSystem from '@deepseek-ai/dsh-fs-sandbox'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { LocalSandboxProvider } from '@deepseek-ai/dsh-sandbox-local'
+import { seatbeltProfileArgs } from '@deepseek-ai/dsh-sandbox-local/src/profiles.ts'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import type { ToolResult } from '@deepseek-ai/dsh-tools'
+import { launcherPath } from 'node-addon-landlock-run'
+import * as agentSpine from '../src/index.ts'
+
+const bwrapUsable = spawnSync('bwrap', [
+  '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--die-with-parent', '--', 'true',
+], { timeout: 5_000, stdio: 'ignore' }).status === 0
+const landlockUsable = spawnSync(launcherPath(), ['--probe'], { timeout: 5_000, stdio: 'ignore' }).status === 0
+const seatbeltUsable = process.platform === 'darwin'
+  && spawnSync('sandbox-exec', [...seatbeltProfileArgs({ mode: 'workspace-write', workspaceRoot: homedir() }), '--', 'true'], { timeout: 5_000, stdio: 'ignore' }).status === 0
+const processSandboxUsable = bwrapUsable || landlockUsable || seatbeltUsable
+
+let ctx: Context | undefined
+let projectA: string
+let projectB: string
+const tempDirs: string[] = []
+
+async function projectDir(label: string): Promise<string> {
+  const dir = await mkdtemp(join(homedir(), `dsh-${label}-`))
+  tempDirs.push(dir)
+  return dir
+}
+
+async function expectMissing(path: string): Promise<void> {
+  await expect(readFile(path, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' })
+}
+
+function resultText(result: ToolResult): string {
+  return result.content.flatMap(block => block.type === 'text' ? [block.text] : []).join('\n')
+}
+
+beforeEach(async () => {
+  projectA = await projectDir('project-a')
+  projectB = await projectDir('project-b')
+  const fallbackRoot = await projectDir('fallback')
+
+  ctx = new Context()
+  await ctx.plugin(LocalSandboxProvider, {})
+  await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: fallbackRoot })
+  await ctx.plugin(SandboxBashExecutor, { cwd: fallbackRoot, timeoutMs: 30_000 })
+  await ctx.plugin(SandboxedFileSystem, { cwd: fallbackRoot })
+  await ctx.plugin(agentSpine, {
+    workspaceContext: false,
+    skills: { enabled: false },
+    toolBash: { enableRunInBackground: false },
+    toolTasks: false,
+  })
+  await new Promise(resolve => setTimeout(resolve, 50))
+  await ctx.plugin(FsPolicy)
+  await ctx.plugin(ToolFs)
+})
+
+afterEach(async () => {
+  await ctx?.fiber.dispose()
+  ctx = undefined
+  await Promise.all(tempDirs.splice(0).map(dir => rm(dir, { recursive: true, force: true })))
+})
+
+async function agents() {
+  const active = ctx as Context
+  const [a, b] = await Promise.all([
+    active.agents.create({ sessionId: SessionId('project-a-session'), meta: { cwd: projectA } }),
+    active.agents.create({ sessionId: SessionId('project-b-session'), meta: { cwd: projectB } }),
+  ])
+  return { active, agentA: a.agent, agentB: b.agent }
+}
+
+describe('one-context multi-project sandbox', () => {
+  it.skipIf(!processSandboxUsable)('confines concurrent bash calls to each calling session workspace', async () => {
+    const { active, agentA, agentB } = await agents()
+    const [aOwn, bOwn, aCross, bCross] = await Promise.all([
+      active.tools.execute({
+        callId: CallId('bash-a-own'), name: 'bash', agent: agentA,
+        signal: new AbortController().signal,
+        arguments: { command: 'printf a > a-owned.txt', description: 'Write project A marker' },
+      }),
+      active.tools.execute({
+        callId: CallId('bash-b-own'), name: 'bash', agent: agentB,
+        signal: new AbortController().signal,
+        arguments: { command: 'printf b > b-owned.txt', description: 'Write project B marker' },
+      }),
+      active.tools.execute({
+        callId: CallId('bash-a-cross'), name: 'bash', agent: agentA,
+        signal: new AbortController().signal,
+        arguments: { command: `printf cross > ../${basename(projectB)}/from-a.txt`, description: 'Attempt project B write' },
+      }),
+      active.tools.execute({
+        callId: CallId('bash-b-cross'), name: 'bash', agent: agentB,
+        signal: new AbortController().signal,
+        arguments: { command: `printf cross > ../${basename(projectA)}/from-b.txt`, description: 'Attempt project A write' },
+      }),
+    ])
+
+    expect(aOwn.isError).toBe(false)
+    expect(bOwn.isError).toBe(false)
+    expect(aCross.isError).toBe(false)
+    expect(bCross.isError).toBe(false)
+    expect(resultText(aCross)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(resultText(bCross)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(await readFile(join(projectA, 'a-owned.txt'), 'utf8')).toBe('a')
+    expect(await readFile(join(projectB, 'b-owned.txt'), 'utf8')).toBe('b')
+    await expectMissing(join(projectB, 'from-a.txt'))
+    await expectMissing(join(projectA, 'from-b.txt'))
+  })
+
+  it('confines concurrent filesystem writes to each calling session workspace', async () => {
+    const { active, agentA, agentB } = await agents()
+    const [aOwn, bOwn, aCross, bCross] = await Promise.all([
+      active.tools.execute({
+        callId: CallId('fs-a-own'), name: 'write', agent: agentA,
+        signal: new AbortController().signal,
+        arguments: { file_path: 'a-owned.txt', content: 'a' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-b-own'), name: 'write', agent: agentB,
+        signal: new AbortController().signal,
+        arguments: { file_path: 'b-owned.txt', content: 'b' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-a-cross'), name: 'write', agent: agentA,
+        signal: new AbortController().signal,
+        arguments: { file_path: join(projectB, 'from-a.txt'), content: 'cross' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-b-cross'), name: 'write', agent: agentB,
+        signal: new AbortController().signal,
+        arguments: { file_path: join(projectA, 'from-b.txt'), content: 'cross' },
+      }),
+    ])
+
+    expect(aOwn.isError).toBe(false)
+    expect(bOwn.isError).toBe(false)
+    expect(aCross.isError).toBe(true)
+    expect(bCross.isError).toBe(true)
+    expect(resultText(aCross)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(resultText(bCross)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(await readFile(join(projectA, 'a-owned.txt'), 'utf8')).toBe('a')
+    expect(await readFile(join(projectB, 'b-owned.txt'), 'utf8')).toBe('b')
+    await expectMissing(join(projectB, 'from-a.txt'))
+    await expectMissing(join(projectA, 'from-b.txt'))
+  })
+
+  it.skipIf(!processSandboxUsable)('keeps symlink-sensitive session cwd semantics aligned across bash, fs, and policy', async () => {
+    const active = ctx as Context
+    const lexicalRoot = await projectDir('lexical-workspace')
+    const physicalRoot = await projectDir('physical-workspace')
+    const physicalChild = join(physicalRoot, 'child')
+    await mkdir(physicalChild)
+    const link = join(lexicalRoot, 'link')
+    await symlink(physicalChild, link, process.platform === 'win32' ? 'junction' : 'dir')
+    const sessionCwd = `${link}/..`
+    const handle = await active.agents.create({
+      sessionId: SessionId('symlink-parent-session'),
+      meta: { cwd: sessionCwd },
+    })
+
+    const [bashOwn, bashLexical, fsOwn, fsLexical] = await Promise.all([
+      active.tools.execute({
+        callId: CallId('bash-symlink-own'), name: 'bash', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { command: 'printf bash > bash-owned.txt', description: 'Write physical workspace marker' },
+      }),
+      active.tools.execute({
+        callId: CallId('bash-symlink-lexical'), name: 'bash', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { command: `printf escaped > ${join(lexicalRoot, 'bash-escaped.txt')}`, description: 'Attempt lexical workspace write' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-symlink-own'), name: 'write', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { file_path: 'fs-owned.txt', content: 'fs' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-symlink-lexical'), name: 'write', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { file_path: join(lexicalRoot, 'fs-escaped.txt'), content: 'escaped' },
+      }),
+    ])
+
+    expect(bashOwn.isError).toBe(false)
+    expect(resultText(bashOwn)).not.toContain('[sandbox:')
+    expect(bashLexical.isError).toBe(false)
+    expect(resultText(bashLexical)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(fsOwn.isError).toBe(false)
+    expect(fsLexical.isError).toBe(true)
+    expect(resultText(fsLexical)).toContain('[sandbox: file access denied under workspace-write mode]')
+    expect(await readFile(join(physicalRoot, 'bash-owned.txt'), 'utf8')).toBe('bash')
+    expect(await readFile(join(physicalRoot, 'fs-owned.txt'), 'utf8')).toBe('fs')
+    await expectMissing(join(lexicalRoot, 'bash-escaped.txt'))
+    await expectMissing(join(lexicalRoot, 'fs-escaped.txt'))
+  })
+
+  it.skipIf(!processSandboxUsable)('resolves parent traversal from a symlinked session root consistently', async () => {
+    const active = ctx as Context
+    const lexicalRoot = await projectDir('lexical-parent')
+    const physicalRoot = await projectDir('physical-parent')
+    const physicalChild = join(physicalRoot, 'child')
+    await mkdir(physicalChild)
+    const link = join(lexicalRoot, 'link')
+    await symlink(physicalChild, link, process.platform === 'win32' ? 'junction' : 'dir')
+    await writeFile(join(lexicalRoot, 'shared.txt'), 'from-lexical-parent')
+    await writeFile(join(physicalRoot, 'shared.txt'), 'from-physical-parent')
+    const handle = await active.agents.create({
+      sessionId: SessionId('symlink-root-parent-path-session'),
+      meta: { cwd: link },
+    })
+
+    const [bashRead, fsRead] = await Promise.all([
+      active.tools.execute({
+        callId: CallId('bash-symlink-parent-read'), name: 'bash', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { command: 'cat ../shared.txt', description: 'Read through the physical parent' },
+      }),
+      active.tools.execute({
+        callId: CallId('fs-symlink-parent-read'), name: 'read', agent: handle.agent,
+        signal: new AbortController().signal,
+        arguments: { file_path: '../shared.txt' },
+      }),
+    ])
+
+    expect(bashRead.isError).toBe(false)
+    expect(fsRead.isError).toBe(false)
+    expect(resultText(bashRead)).toContain('from-physical-parent')
+    expect(resultText(fsRead)).toContain('from-physical-parent')
+    expect(resultText(bashRead)).not.toContain('from-lexical-parent')
+    expect(resultText(fsRead)).not.toContain('from-lexical-parent')
+  })
+})
--- a/packages/examples/cli-demo/src/cli.ts
+++ b/packages/examples/cli-demo/src/cli.ts
@@ -14,7 +14,7 @@ import { boot, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 const CLI_NAME = 'dsh-cli-demo'
 const DEFAULT_CONFIG_PATH = './cordis.yml'
 const OUTPUT_FORMATS = ['text', 'json', 'stream-json'] as const
-const USAGE = `Usage: ${CLI_NAME} [--config path] [--output-format text|json|stream-json] <task>\n`
+const USAGE = `Usage: ${CLI_NAME} [--config path] [--output-format text|json|stream-json] (-p <task> | <task>)\n`

 /** Supported CLI output encodings. */
 export type OutputFormat = typeof OUTPUT_FORMATS[number]
@@ -73,6 +73,7 @@ interface ParsedArguments {
    readonly config?: string
    readonly 'output-format'?: string
    readonly help?: boolean
+    readonly prompt?: string
  }
  readonly positionals: string[]
 }
@@ -129,6 +130,7 @@ export function parseCliArgs(args: readonly string[]): CliCommand {
        config: { type: 'string' },
        'output-format': { type: 'string' },
        help: { type: 'boolean' },
+        prompt: { type: 'string', short: 'p' },
      },
      allowPositionals: true,
      strict: true,
@@ -138,12 +140,16 @@ export function parseCliArgs(args: readonly string[]): CliCommand {
  }

  if (parsed.values.help === true) return { kind: 'help' }
-  if (parsed.positionals.length !== 1) {
-    throw new CliArgumentError(`expected exactly one positional task, received ${parsed.positionals.length}`)
+  const prompt = parsed.values.prompt
+  if (prompt !== undefined && parsed.positionals.length > 0) {
+    throw new CliArgumentError('-p/--prompt and a positional task are mutually exclusive')
  }
-  // Cardinality was checked above, so index zero exists.
+  if (prompt === undefined && parsed.positionals.length !== 1) {
+    throw new CliArgumentError(`expected exactly one positional task or -p, received ${parsed.positionals.length} positional(s)`)
+  }
+  // Cardinality was checked above, so the fallback index zero exists.
  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  const task = parsed.positionals[0]!
+  const task = prompt ?? parsed.positionals[0]!
  if (task.trim().length === 0) throw new CliArgumentError('task must not be blank')

  const requestedFormat = parsed.values['output-format'] ?? 'text'
--- a/packages/examples/cli-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts
@@ -8,6 +8,15 @@ import { fileURLToPath } from 'node:url'
 import { zstdDecompress } from 'node:zlib'
 import { afterEach, describe, expect, it } from 'vitest'

+/**
+ * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer.
+ * The consumer's mock model is an example-local TypeScript plugin (Node 22.19+ — the engines
+ * floor — strips types natively, so plain `node` loads it), its config carries a `disabled:
+ * true` unresolvable entry (the fail-loud entry-load guard must not mistake an intentionally
+ * fiber-less entry for a failed import), and the optional spill pair loads from the consumer
+ * install — so every passing boot proves all three alongside the CLI's own output contract.
+ */
+
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
 const cliBin = join(repoRoot, 'packages/examples/cli-demo/lib/bin.js')
 const decompress = promisify(zstdDecompress)
@@ -18,6 +27,7 @@ const dshPackages = [
  'session-persistence/session-persistence', 'session-persistence/session-checkpoint-policy',
  'session-persistence/session-persistence-jsonl',
  'context/workspace-context',
+  'spill/spill', 'spill/spill-local', 'spill/spill-policy', 'util/retention',
 ]
 const vendorPackages = ['cordis', 'loader', 'include', 'timer', 'schemastery', 'cosmokit']

@@ -36,15 +46,18 @@ async function makeConsumer(): Promise<string> {
  const nodeModules = join(dir, 'node_modules')
  for (const rel of dshPackages) await linkPackage(join(repoRoot, 'packages', rel), nodeModules)
  for (const rel of vendorPackages) await linkPackage(join(repoRoot, 'vendor', rel), nodeModules)
-  await writeFile(join(dir, 'mock-llm.mjs'), [
-    "import { LlmAdapter } from '@deepseek-ai/dsh-llm'",
+  await writeFile(join(dir, 'mock-llm.ts'), [
+    // Real type annotations: this file exists to prove plain Node's type
+    // stripping loads an example-local TS plugin from a built consumer.
+    "import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'",
+    "import type { Context } from 'cordis'",
    'class Mock extends LlmAdapter {',
-    '  async * stream(options) {',
-    "    const text = options.messages.flatMap(message => message.content).filter(block => block.type === 'text').at(-1)?.text ?? ''",
+    '  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {',
+    "    const text: string = options.messages.flatMap(message => message.content).filter(block => block.type === 'text').at(-1)?.text ?? ''",
    "    yield { type: 'block-start', index: 0, blockType: 'text' }",
    "    if (text === 'hang') {",
    "      yield { type: 'text-delta', index: 0, text: 'partial' }",
-    '      await new Promise((resolve, reject) => {',
+    '      await new Promise<never>((resolve, reject) => {',
    "        const timer = setTimeout(() => reject(new Error('hang timeout')), 30000)",
    "        const onAbort = () => { clearTimeout(timer); reject(new Error('aborted')) }",
    '        if (options.signal.aborted) onAbort()',
@@ -61,12 +74,12 @@ async function makeConsumer(): Promise<string> {
    '}',
    "export const name = 'built-cli-mock'",
    "export const inject = ['llm']",
-    "export function apply(ctx) { ctx.llm.registerAdapter(['built-cli-mock'], new Mock()) }",
+    "export function apply(ctx: Context) { ctx.llm.registerAdapter(['built-cli-mock'], new Mock()) }",
    '',
  ].join('\n'))
  await writeFile(join(dir, 'cordis.yml'), [
    '- id: mock-llm',
-    "  name: './mock-llm.mjs'",
+    "  name: './mock-llm.ts'",
    '- id: bash',
    "  name: '@deepseek-ai/dsh-bash-local'",
    '- id: cli-agent',
@@ -77,6 +90,18 @@ async function makeConsumer(): Promise<string> {
    "    persona: 'built CLI test'",
    "    persistenceRoot: './.sessions'",
    '    workspaceContext: false',
+    '- id: spill-local',
+    "  name: '@deepseek-ai/dsh-spill-local'",
+    '- id: spill-policy',
+    "  name: '@deepseek-ai/dsh-spill-policy'",
+    '  config:',
+    '    maxInlineBytes: 50000',
+    // A `disabled: true` entry settles without a fiber by design; the fail-loud
+    // entry-load guard must not mistake it for a failed import. The nonexistent
+    // path makes that distinction observable while a clean run proves boot continued.
+    '- id: off',
+    "  name: './does-not-exist.ts'",
+    '  disabled: true',
    '',
  ].join('\n'))
  return dir
--- a/packages/examples/cli-demo/tests/cli.spec.ts
+++ b/packages/examples/cli-demo/tests/cli.spec.ts
@@ -162,15 +162,19 @@ describe('parseCliArgs', () => {
      kind: 'run', configPath: 'custom.yml', outputFormat: 'stream-json', task: 'do it',
    })
    expect(parseCliArgs(['--', '-task'])).toMatchObject({ task: '-task' })
+    expect(parseCliArgs(['-p', 'flag task'])).toMatchObject({ task: 'flag task' })
+    expect(parseCliArgs(['--prompt', 'long-flag task'])).toMatchObject({ task: 'long-flag task' })
    expect(parseCliArgs(['--help', 'ignored'])).toEqual({ kind: 'help' })
  })

  it('rejects missing, blank, extra, invalid-format, and unsupported flags', () => {
    expect(() => parseCliArgs([])).toThrow('received 0')
    expect(() => parseCliArgs(['   '])).toThrow('must not be blank')
+    expect(() => parseCliArgs(['-p', '   '])).toThrow('must not be blank')
    expect(() => parseCliArgs(['one', 'two'])).toThrow('received 2')
+    expect(() => parseCliArgs(['-p', 'task', 'positional'])).toThrow('mutually exclusive')
    expect(() => parseCliArgs(['--output-format', 'xml', 'task'])).toThrow('unsupported output format')
-    expect(() => parseCliArgs(['-p', 'task'])).toThrow('Unknown option')
+    expect(() => parseCliArgs(['-x', 'task'])).toThrow('Unknown option')
  })
 })

--- a/packages/examples/tui-demo/src/bin.ts
+++ b/packages/examples/tui-demo/src/bin.ts
@@ -11,8 +11,16 @@ import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/
 const NAME = 'dsh-tui-demo'

 /* v8 ignore start -- thin self-executing composition over the unit-tested
-   dsh-app-boot helpers; exercised end-to-end by the keyless Loader-path and
-   built-bin smokes */
+   dsh-app-boot helpers; exercised end-to-end by the tui-agent PTY smoke and
+   the built-bin fail-loud smoke */
+// Refuse pipes BEFORE booting: a compose-time throw inside the Loader tree is
+// logged per-entry rather than rethrown, so a piped launch would otherwise
+// settle into an idle UI-less process instead of exiting nonzero.
+if (!process.stdin.isTTY || !process.stdout.isTTY) {
+  process.stderr.write(`${NAME}: the TUI requires stdin and stdout to be interactive TTYs; `
+    + 'use the one-shot dsh-cli-demo bin for pipes and automation\n')
+  process.exit(1)
+}
 installFailLoud(NAME)
 loadEnv(NAME)
 await boot(NAME, resolveConfigPath(process.argv[2] ?? './cordis.yml', undefined))
--- a/packages/examples/tui-demo/src/index.ts
+++ b/packages/examples/tui-demo/src/index.ts
@@ -28,7 +28,6 @@ import * as uiTui from '@deepseek-ai/dsh-tui'

 export const name = 'tui-demo'
 const DEFAULT_PERSISTENCE_ROOT = './.sessions'
-const DEFAULT_WELCOME = 'ready.'

 /** App config routed to the spine, TUI, configured agent, and JSONL backend. */
 export interface Config {
@@ -52,8 +51,15 @@ export interface Config {
  persistenceRoot?: string
  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
  persistenceCompression?: JsonlCompression
-  /** TUI subtitle rendered on start. Defaults to `ready.`. */
+  /** TUI transcript's optional first line; absent renders nothing on start. */
  welcome?: string
+  /**
+   * Shell command template the TUI prints on exit and lists under `/resume`,
+   * with `{session}` replaced by the live session id (forwarded to the front
+   * door). Set it to a command that resumes via this app's env var, e.g.
+   * `RESUME_SESSION_ID={session} dsh`.
+   */
+  resumeCommand?: string
  /** Full-screen TUI presentation settings. */
  ui?: uiTui.TuiConfig
  /** Skill registry, local-provider, and model-facing consumer config. */
@@ -85,7 +91,8 @@ export const Config: z<Config> = z.object({
  sessionTitle: agentCore.SessionTitleConfigSchema,
  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
  persistenceCompression: JsonlCompressionSchema,
-  welcome: z.string().default(DEFAULT_WELCOME),
+  welcome: z.string(),
+  resumeCommand: z.string(),
  ui: uiTui.TuiConfigSchema,
  skills: agentCore.SkillConfigSchema,
  toolBash: agentCore.ToolBashConfigSchema,
@@ -117,7 +124,8 @@ export function composeTuiApp(ctx: Context, config: Config): void {
  ctx.plugin(UserInteractionService)
  ctx.plugin(uiTui, {
    ...config.ui,
-    welcome: config.welcome ?? DEFAULT_WELCOME,
+    ...config.welcome === undefined ? {} : { welcome: config.welcome },
+    ...config.resumeCommand === undefined ? {} : { resumeCommand: config.resumeCommand },
    sessionId,
  })
  ctx.plugin(agentCore, {
--- a/packages/examples/tui-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/tui-demo/tests/built-bin.e2e.ts
@@ -0,0 +1,98 @@
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, mkdir, rm, symlink, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+
+/**
+ * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer.
+ * The TUI app owns no non-TTY fallback, so the piped subprocess must refuse to boot with a
+ * nonzero exit and a stderr pointer at the one-shot CLI — the bin guards BEFORE the Loader
+ * because a compose-time throw inside the tree is logged per-entry, not rethrown. The consumer
+ * links only the bin's import chain (dsh-app-boot and its vendored Loader stack): the refusal
+ * fires before any config is read, so no plugin tree is needed. Missing-config fail-loud and
+ * full-boot coverage for the shared dsh-app-boot glue live in cli-demo's built-bin suite; it
+ * skips before build, and interactive TTY behavior is PTY-covered by examples/tui-agent (the
+ * one sanctioned PTY surface).
+ */
+
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const tuiBin = join(repoRoot, 'packages/examples/tui-demo/lib/bin.js')
+
+// Symlink each package the bin imports at module load by package name so plain
+// Node resolves its built `main`, matching an installed dependency rather than
+// tsconfig paths.
+const dshPackages = ['examples/tui-demo', 'ui/app-boot']
+const vendorPackages = ['cordis', 'loader', 'include', 'schemastery', 'cosmokit']
+
+async function pkgName(absDir: string): Promise<string> {
+  const json = JSON.parse(await readFile(join(absDir, 'package.json'), 'utf8')) as { name: string }
+  return json.name
+}
+
+/** Build a temporary external consumer with built workspace/vendor links. */
+async function makeConsumer(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'tui-built-bin-'))
+  const nm = join(dir, 'node_modules')
+  for (const rel of dshPackages) {
+    const abs = join(repoRoot, 'packages', rel)
+    const target = join(nm, await pkgName(abs))
+    await mkdir(dirname(target), { recursive: true })
+    await symlink(abs, target)
+  }
+  for (const v of vendorPackages) {
+    const abs = join(repoRoot, 'vendor', v)
+    const target = join(nm, await pkgName(abs))
+    await mkdir(dirname(target), { recursive: true })
+    await symlink(abs, target)
+  }
+  return dir
+}
+
+/** Run the built bin in `cwd` with PIPED stdio; resolve with output + exit code. */
+function runBuiltBin(cwd: string): Promise<{ stdout: string; code: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    // NO tsx — this is the published `node lib/bin.js` path (`--expose-internals`
+    // matches the demo command; the guard fires before the Loader needs it).
+    const child = spawn(process.execPath, ['--expose-internals', tuiBin, './cordis.yml'], {
+      cwd,
+      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (c: string) => { stdout += c })
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (c: string) => { stderr += c })
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      reject(new Error(`built bin did not exit within 25s. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, 25_000)
+    child.on('exit', (code) => { clearTimeout(timer); resolve({ stdout, code: code ?? -1, stderr }) })
+    child.on('error', (err) => { clearTimeout(timer); reject(err) })
+    child.stdin.end()
+  })
+}
+
+let consumer: string | undefined
+
+afterEach(async () => {
+  // Windows can briefly retain released handles after exit; retry removal.
+  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
+  consumer = undefined
+})
+
+describe.skipIf(!existsSync(tuiBin))('dsh-tui-demo BUILT bin (node lib/bin.js, no tsx)', () => {
+  it('refuses pipes LOUD (non-zero exit + stderr) before booting the Loader', async () => {
+    consumer = await makeConsumer()
+    const { stdout, code, stderr } = await runBuiltBin(consumer)
+    expect(code).not.toBe(0)
+    expect(stderr).toContain('requires stdin and stdout to be interactive TTYs')
+    expect(stderr).toContain('dsh-cli-demo')
+    // The refusal happens before any plugin mounts: stdout stays silent.
+    expect(stdout).toBe('')
+  }, 30_000)
+})
--- a/packages/examples/tui-demo/tests/tui-agent.spec.ts
+++ b/packages/examples/tui-demo/tests/tui-agent.spec.ts
@@ -33,6 +33,7 @@ describe('dsh-tui-demo app', () => {
      persistenceRoot: '/tmp/tui-sessions',
      persistenceCompression: 'none',
      welcome: 'TUI ready',
+      resumeCommand: 'dsh --resume {session}',
      ui: { color: false, maxToolOutputLines: 3 },
      skills: { tool: { catalogDescriptionMaxLength: 8 } },
      toolBash: { enableRunInBackground: false },
@@ -53,7 +54,12 @@ describe('dsh-tui-demo app', () => {
    expect(calls[0]?.config).toBeUndefined()
    expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
    const tuiConfig = calls[5]?.config as { sessionId: string }
-    expect(tuiConfig).toMatchObject({ welcome: 'TUI ready', color: false, maxToolOutputLines: 3 })
+    expect(tuiConfig).toMatchObject({
+      welcome: 'TUI ready',
+      resumeCommand: 'dsh --resume {session}',
+      color: false,
+      maxToolOutputLines: 3,
+    })
    expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
    const spineConfig = calls[6]?.config as {
      readonly agents: Array<Record<string, unknown>>
@@ -89,7 +95,8 @@ describe('dsh-tui-demo app', () => {
    })

    expect(calls[2]?.config).toEqual({ root: './.sessions' })
-    expect(calls[5]?.config).toEqual({ welcome: 'ready.', sessionId: 'persisted-session' })
+    // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
+    expect(calls[5]?.config).toEqual({ sessionId: 'persisted-session' })
    expect((calls[6]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
      id: 'main',
      resumeSessionId: 'persisted-session',