Merge remote-tracking branch 'origin/master' into codex/session-scoped-sandbox-roots

# Conflicts: # .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml # .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md # .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md # examples/acp-agent/README.md # packages/examples/agent-spine-demo/package.json # packages/fs/fs-sandbox/src/index.ts # packages/fs/tool-fs-search/tests/tools.spec.ts # packages/support/acp-snapshot/README.md # packages/support/acp-snapshot/src/suite.ts # pnpm-lock.yaml # scripts/type-equiv.manifest.json
2026-07-22 21:37:30 +08:00
parent aaee0c0c22 402f8c5f5a
commit 10a55d7a27
1133 changed files with 67897 additions and 10909 deletions
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -4,7 +4,7 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling

 | Package | npm name | Role |
 |---|---|---|
-| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin, with an opt-in persisted-goal stack |
+| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin, with fallback session titles and an opt-in persisted-goal stack |
 | `tui-demo/` | `@deepseek-ai/dsh-tui-demo` | Full-screen terminal app: the spine + persisted goals + `/goal` command + JSONL persistence + `dsh-tui` + a pre-created `main` agent, with a boot `bin` |
 | `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | Headless one-shot app: the spine + JSONL persistence + a pre-created `main` agent, with text and DSH-native JSON output |
 | `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + persisted goals + `/goal` command + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` |
--- a/packages/examples/acp-demo/README.md
+++ b/packages/examples/acp-demo/README.md
@@ -33,6 +33,7 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 | `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
 | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
+| `sessionTitle` | spine example limits | fallback title word/byte limits routed through `dsh-agent-spine-demo` |
 | `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
 | `workspaceContext` | (required) | workspace-instruction byte budget/config, or `false`; routed to the providerless-safe `dsh-workspace-context` plugin |
 | `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` |
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -50,6 +50,8 @@ export interface Config {
  tools?: ToolsConfig
  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
  dshHome?: string
+  /** Fallback session-title limits forwarded through agent-spine-demo. */
+  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
@@ -82,6 +84,7 @@ export const Config: z<Config> = z.object({
  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
  tools: ToolRegistry.Config,
  dshHome: z.string(),
+  sessionTitle: agentCore.SessionTitleConfigSchema,
  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
  persistenceCompression: JsonlCompressionSchema,
  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -12,6 +12,7 @@ Read this package for the whole plugin tree and its composition order.
@cordisjs/plugin-timer            timer service (writes nothing to stdout)
@deepseek-ai/dsh-llm              abstract LLM service + content-block vocabulary
@deepseek-ai/dsh-session          event-sourced session log + store
+@deepseek-ai/dsh-session-title    log-backed title service + deterministic fallback
@deepseek-ai/dsh-system-prompt    prompt-section + tool-schema assembly
@deepseek-ai/dsh-tools            registry + guarded pre/around/post/final-result pipeline
@deepseek-ai/dsh-skill            skill provider registry
@@ -41,6 +42,7 @@ Read this package for the whole plugin tree and its composition order.
 The spine is everything COMMON to every front door. The swappable and front-door-coupled pieces stay out, picked by whatever loads the bundle:

 - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
+- **model-backed session-title providers** — the bundle mounts the fallback service with overridable example limits (5 words, 40 fallback bytes, 80 accepted-title bytes); a leaf may opt into exactly one first-message or all-messages LLM provider.
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
 - **presentation + per-app infra** — the terminal TUI or ACP front door and `hmr`. These form the coupled front-door cluster that the app packages ([`dsh-tui-demo`](../tui-demo/README.md), [`dsh-acp-demo`](../acp-demo/README.md)) bake in. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.
@@ -51,11 +53,11 @@ This is the [interface/implementation/consumer seam](../../../.agents/notes/impl

 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants?, llmRetry? }
+// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants?, llmRetry? }
 // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```

-The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `llmRetry` to the bounded retry policy; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); `invariants` to the invariant service; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
+The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `llmRetry` to the bounded retry policy; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `sessionTitle` to the fallback title service; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); `invariants` to the invariant service; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. Omitted `sessionTitle` uses the explicit example policy of 5 words, 40 fallback bytes, and 80 accepted-title bytes. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.

 For example, `{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` keeps the package-owned companions mounted but suppresses the blocked owner. Blocklist matches override allowlist matches; see [`dsh-invariants`](../../support/invariants/README.md) for regex and lifecycle rules.

--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-agent-spine-demo",
-  "description": "The default executor-less/UI-less agent spine with bounded retry and optional persisted goals",
+  "description": "The default executor-less/UI-less agent spine with fallback session titles, bounded retry, and optional persisted goals",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -32,12 +32,13 @@
    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
    "@deepseek-ai/dsh-goal": "^0.0.1",
    "@deepseek-ai/dsh-goal-session": "^0.0.1",
-    "@deepseek-ai/dsh-home": "^0.0.1",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-paths": "^0.0.1",
    "@deepseek-ai/dsh-llm-retry": "^0.0.1",
    "@deepseek-ai/dsh-scope": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-title": "^0.0.1",
    "@deepseek-ai/dsh-skill": "^0.0.1",
    "@deepseek-ai/dsh-skill-local": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -60,14 +61,15 @@
    "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
    "@deepseek-ai/dsh-goal": "workspace:^",
    "@deepseek-ai/dsh-goal-session": "workspace:^",
-    "@deepseek-ai/dsh-home": "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:^",
    "@deepseek-ai/dsh-skill": "workspace:^",
    "@deepseek-ai/dsh-skill-local": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/examples/agent-spine-demo/src/index.ts
+++ b/packages/examples/agent-spine-demo/src/index.ts
@@ -13,6 +13,7 @@ import Timer from '@cordisjs/plugin-timer'
 import z from 'schemastery'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
+import SessionTitleService, { type Config as SessionTitleConfig } from '@deepseek-ai/dsh-session-title'
 import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import SkillService, { type Config as SkillRegistryConfig } from '@deepseek-ai/dsh-skill'
@@ -33,10 +34,17 @@ import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
 import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
 import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'
 import * as llmRetry from '@deepseek-ai/dsh-llm-retry'
-import { resolveDshHome } from '@deepseek-ai/dsh-home'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'

 export const name = 'agent-spine-demo'

+/** Overridable example policy used when a bundle consumer omits `sessionTitle`. */
+const EXAMPLE_SESSION_TITLE_CONFIG: SessionTitleConfig = {
+  fallbackMaxWords: 5,
+  fallbackMaxBytes: 40,
+  maxTitleBytes: 80,
+}
+
 /** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
 export interface SkillConfig {
  /** Mount the bundled local skill provider and model-facing skill tool (default true). */
@@ -63,7 +71,8 @@ export interface GoalConfig {
 * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
 * plugin (the deployment's persona section and the explicit model-facing tool
 * order), the `tools` object to the tool registry (its presentation `mode`),
- * `dshHome` to bash environment and local skill discovery, `skills` to the
+ * `dshHome` to bash environment and local skill discovery, `sessionTitle` to
+ * the fallback title service, `skills` to the
 * skill registry/local provider/tool consumer, `workspaceContext` to the
 * workspace-context loader, `llmRetry` to the bounded request-recovery policy,
 * and `toolBash`/`toolTasks` to the model-facing tool plugins this bundle owns.
@@ -88,6 +97,8 @@ export interface Config {
  tools?: ToolsConfig
  /** DeepSeek Harness home directory shared by shell context and local skill discovery. */
  dshHome?: string
+  /** Deterministic fallback and accepted-title limits; omission uses the bundle's example policy. */
+  sessionTitle?: SessionTitleConfig
  /** Workspace-context loader controls with an explicit byte budget; set `false` for hermetic prompts. */
  workspaceContext: workspaceContext.Config | false
  /** Skill registry, local provider, and model-facing consumer config. */
@@ -112,6 +123,10 @@ export const SkillConfigSchema: z<SkillConfig> = z.object({
  tool: toolSkill.Config,
 })

+/** The session-title config schema with the shared bundle's overridable example limits. */
+export const SessionTitleConfigSchema: z<SessionTitleConfig> = SessionTitleService.Config
+  .default(EXAMPLE_SESSION_TITLE_CONFIG)
+
 /** The bash-tool config schema exported for app packages that forward `toolBash`. */
 export const ToolBashConfigSchema: z<toolBash.Config> = toolBash.Config

@@ -134,6 +149,7 @@ export const Config = z.intersect([
  z.object({
    tools: ToolRegistry.Config,
    dshHome: z.string(),
+    sessionTitle: SessionTitleConfigSchema,
    skills: SkillConfigSchema,
    workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
    toolBash: ToolBashConfigSchema,
@@ -141,7 +157,7 @@ export const Config = z.intersect([
    invariants: InvariantService.Config,
    goals: z.union([z.const(false), GoalConfigSchema]),
    llmRetry: LlmRetryConfigSchema,
-  }) as unknown as z<Pick<Config, 'tools' | 'dshHome' | 'skills' | 'workspaceContext' | 'toolBash' | 'toolTasks' | 'invariants' | 'goals' | 'llmRetry'>>,
+  }) as unknown as z<Pick<Config, 'tools' | 'dshHome' | 'sessionTitle' | 'skills' | 'workspaceContext' | 'toolBash' | 'toolTasks' | 'invariants' | 'goals' | 'llmRetry'>>,
 ]) as unknown as z<Config>

 /**
@@ -156,6 +172,7 @@ export function pickSpineConfig(config: Omit<Config, 'agents'>): Omit<Config, 'a
    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
    ...config.tools !== undefined ? { tools: config.tools } : {},
    ...config.dshHome !== undefined ? { dshHome: config.dshHome } : {},
+    ...config.sessionTitle !== undefined ? { sessionTitle: config.sessionTitle } : {},
    workspaceContext: config.workspaceContext,
    ...config.skills !== undefined ? { skills: config.skills } : {},
    ...config.toolBash !== undefined ? { toolBash: config.toolBash } : {},
@@ -187,6 +204,7 @@ export function apply(ctx: Context, config: Config): void {
  ctx.plugin(Timer)
  ctx.plugin(LlmService)
  ctx.plugin(SessionStore)
+  ctx.plugin(SessionTitleService, config.sessionTitle ?? EXAMPLE_SESSION_TITLE_CONFIG)
  // Owner schemas resolve defaults; forward toolOrder only when explicitly set.
  ctx.plugin(SystemPrompt, {
    persona: config.persona ?? '',
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -17,6 +17,8 @@ import * as agentInvariant from '@deepseek-ai/dsh-agent/invariant'
 import * as scopeInvariant from '@deepseek-ai/dsh-scope/invariant'
 import * as agentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'

+const testToolSignal = new AbortController().signal
+
 declare module '@deepseek-ai/dsh-tasks' {
  interface TaskKindMap {
    probe: 'probe'
@@ -129,6 +131,7 @@ describe('dsh-agent-spine-demo bundle', () => {
    expect(ctx.get('timer')).toBeDefined()
    expect(ctx.get('llm')).toBeDefined()
    expect(ctx.get('sessions')).toBeDefined()
+    expect(ctx.get('sessionTitle')).toBeDefined()
    expect(ctx.get('systemPrompt')).toBeDefined()
    expect(ctx.get('tools')).toBeDefined()
    expect(ctx.get('skills')).toBeDefined()
@@ -140,6 +143,30 @@ describe('dsh-agent-spine-demo bundle', () => {
    await ctx.fiber.dispose()
  })

+  it('forwards configurable fallback title limits to the bundled service', async () => {
+    const ctx = await mount({
+      workspaceContext: false,
+      sessionTitle: {
+        fallbackMaxWords: 1,
+        fallbackMaxBytes: 40,
+        maxTitleBytes: 80,
+      },
+    })
+    const session = ctx.sessions.create(SessionId('configured-title-limits'))
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'One two three four' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(ctx.sessionTitle.get(session)?.title).toBe('One')
+    await ctx.fiber.dispose()
+  })
+
  it('opts into the configured persisted-goal domain, tools, and same-session driver', async () => {
    const ctx = await mount({
      workspaceContext: false,
@@ -216,6 +243,7 @@ describe('dsh-agent-spine-demo bundle', () => {
    expect(retryEvents).toHaveLength(1)
    expect(retryEvents[0]?.data.retry).toBe(1)
    expect(retryEvents[0]?.data.maxRetries).toBe(1)
+    expect(handle.agent.session.events.find(event => event.type === 'session/title')?.data.title).toBe('recover')
    expect(messageText(handle.agent.session.deriveMessages().at(-1))).toBe('recovered by bundled policy')
    await handle.dispose()
    await ctx.fiber.dispose()
@@ -385,6 +413,7 @@ describe('dsh-agent-spine-demo bundle', () => {

    expect((await ctx.skills.list()).map(skill => skill.name)).toEqual(['shared-skill'])
    const execution: ToolExecution = {
+      signal: testToolSignal,
      token: Symbol('agent-core-dsh-home-test') as ToolExecution['token'],
      callId: CallId('agent-core-dsh-home'),
      name: 'bash',
@@ -456,11 +485,12 @@ describe('dsh-agent-spine-demo bundle', () => {
    })
    const wait = vi.spyOn(ctx.tasks, 'wait')
    await ctx.tools.execute({
+      signal: testToolSignal,
      callId: CallId('task-config-forwarding'),
      name: 'task_output',
      arguments: { task_id: id, wait: true },
    })
-    expect(wait).toHaveBeenCalledWith(id, 7, undefined, undefined)
+    expect(wait).toHaveBeenCalledWith(id, 7, undefined, testToolSignal)

    await ctx.fiber.dispose()
  })
@@ -487,6 +517,7 @@ describe('dsh-agent-spine-demo bundle', () => {
      toolOrder: ['zulu'],
      tools: { mode: 'native' as const },
      dshHome: '/tmp/dsh-home',
+      sessionTitle: { fallbackMaxWords: 3, fallbackMaxBytes: 24, maxTitleBytes: 60 },
      workspaceContext: false as const,
      skills: { enabled: false },
      toolBash: { enableRunInBackground: false },
@@ -500,6 +531,7 @@ describe('dsh-agent-spine-demo bundle', () => {
      toolOrder: appConfig.toolOrder,
      tools: appConfig.tools,
      dshHome: appConfig.dshHome,
+      sessionTitle: appConfig.sessionTitle,
      workspaceContext: false,
      skills: appConfig.skills,
      toolBash: appConfig.toolBash,
--- a/packages/examples/agent-spine-demo/tsconfig.json
+++ b/packages/examples/agent-spine-demo/tsconfig.json
@@ -23,6 +23,9 @@
    {
      "path": "../../core/session"
    },
+    {
+      "path": "../../session-title/session-title"
+    },
    {
      "path": "../../core/system-prompt"
    },
@@ -63,7 +66,7 @@
      "path": "../../support/invariants"
    },
    {
-      "path": "../../util/home"
+      "path": "../../util/paths"
    },
    {
      "path": "../../bash/tool-bash"
--- a/packages/examples/cli-demo/README.md
+++ b/packages/examples/cli-demo/README.md
@@ -15,6 +15,7 @@ The package mounts no console logger, interactive UI, user-interaction service,
 | `toolOrder` | lexicographic | explicit model-facing tool order in `dsh-system-prompt` |
 | `tools` | `{ mode: 'native' }` | tool-registry presentation config through `dsh-agent-spine-demo` |
 | `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
+| `sessionTitle` | spine example limits | Fallback title word/byte limits through `dsh-agent-spine-demo` |
 | `skills` | owner defaults | skill registry, local provider, and model-facing skill tool |
 | `toolBash` | owner defaults | model-facing bash config, including this producer's background opt-in |
 | `toolTasks` | owner defaults | generic `task_output` wait bounds |
--- 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'
@@ -181,12 +187,12 @@ async function waitForStartupIdle(agent: Agent, signal?: AbortSignal): Promise<v
    return
  }
  if (signal.aborted) {
-    agent.cancel(interruptionReason(signal))
+    agent.cancel({ kind: 'user' })
    throw new CliInterruptedError(interruptionReason(signal))
  }
  await new Promise<void>((resolve, reject) => {
    const onAbort = (): void => {
-      agent.cancel(interruptionReason(signal))
+      agent.cancel({ kind: 'user' })
      reject(new CliInterruptedError(interruptionReason(signal)))
    }
    signal.addEventListener('abort', onAbort, { once: true })
@@ -243,7 +249,7 @@ export async function runOneShot(ctx: Context, options: OneShotOptions): Promise
      options.onEvent(sessionId, event)
    } catch (error: unknown) {
      outputError = toError(error)
-      agent.cancel('stream output failed')
+      agent.cancel({ kind: 'user' })
    }
  }

@@ -273,7 +279,7 @@ export async function runOneShot(ctx: Context, options: OneShotOptions): Promise
  let onAbort: (() => void) | undefined
  if (signal !== undefined) {
    onAbort = (): void => {
-      agent.cancel(interruptionReason(signal))
+      agent.cancel({ kind: 'user' })
      if (targetTurn === undefined) settleRejected(new CliInterruptedError(interruptionReason(signal)))
    }
    signal.addEventListener('abort', onAbort, { once: true })
@@ -370,7 +376,7 @@ async function bootInterruptibly(
 export function formatTurnFailure(reason: TurnEndReason): string {
  switch (reason.kind) {
    case 'completed': return 'completed'
-    case 'aborted': return reason.reason === undefined ? 'was aborted' : `was aborted: ${reason.reason}`
+    case 'aborted': return 'was aborted'
    case 'error': return `failed at step ${reason.step}: ${'failure' in reason ? reason.failure.message : reason.message}`
    case 'disposed': return 'was disposed'
    case 'max-tokens': return 'reached the model output-token limit'
--- a/packages/examples/cli-demo/src/index.ts
+++ b/packages/examples/cli-demo/src/index.ts
@@ -37,6 +37,8 @@ export interface Config {
  tools?: ToolsConfig
  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
  dshHome?: string
+  /** Fallback session-title limits forwarded through agent-spine-demo. */
+  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
@@ -64,6 +66,7 @@ export const Config: z<Config> = z.object({
  persistenceCompression: JsonlCompressionSchema,
  persona: z.string(),
  dshHome: z.string(),
+  sessionTitle: agentCore.SessionTitleConfigSchema,
  skills: agentCore.SkillConfigSchema,
  // Absent means lexicographic order; schemastery's native array default is [].
  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
--- 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)
@@ -17,6 +26,7 @@ const dshPackages = [
  'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'ui/app-boot',
  'session-persistence/session-persistence', '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']

@@ -35,15 +45,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()',
@@ -60,12 +73,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',
@@ -76,6 +89,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
@@ -179,7 +204,7 @@ describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => {
      )
      expect(result, JSON.stringify(result)).toMatchObject({ code, signal: null })
      expect(result.stdout).toContain('"kind":"aborted"')
-      expect(result.stderr).toContain(`received ${signal}`)
+      expect(result.stderr).toContain('turn 1 was aborted')
    }, 30_000)
  })
 })
--- a/packages/examples/cli-demo/tests/cli-demo.spec.ts
+++ b/packages/examples/cli-demo/tests/cli-demo.spec.ts
@@ -10,6 +10,8 @@ import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import * as cliDemo from '../src/index.ts'

+const testToolSignal = new AbortController().signal
+
 const contexts: Context[] = []

 async function skillConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<cliDemo.Config['skills']>> {
@@ -131,6 +133,7 @@ describe('dsh-cli-demo app composition', () => {

    expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3)
    const execution: ToolExecution = {
+      signal: testToolSignal,
      token: Symbol('cli-demo-dsh-home-test') as ToolExecution['token'],
      callId: CallId('cli-demo-dsh-home'),
      name: 'bash',
@@ -148,11 +151,12 @@ describe('dsh-cli-demo app composition', () => {
    })
    const wait = vi.spyOn(ctx.tasks, 'wait')
    await ctx.tools.execute({
+      signal: testToolSignal,
      callId: CallId('cli-demo-task-config'),
      name: 'task_output',
      arguments: { task_id: id, wait: true },
    })
-    expect(wait).toHaveBeenCalledWith(id, 7, undefined, undefined)
+    expect(wait).toHaveBeenCalledWith(id, 7, undefined, testToolSignal)
  })

  it('accepts false to keep task services without model-facing task controls', async () => {
--- 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')
  })
 })

@@ -398,9 +402,9 @@ describe('runOneShot and executeCli', () => {
    await running
    abort.abort('received SIGINT')
    const output = await outcome
-    expect(JSON.parse(output.stdout)).toMatchObject({ success: false, reason: { kind: 'aborted', reason: 'received SIGINT' } })
+    expect(JSON.parse(output.stdout)).toMatchObject({ success: false, reason: { kind: 'aborted' } })
    expect(output.code).toBe(1)
-    expect(output.stderr).toContain('was aborted: received SIGINT')
+    expect(output.stderr).toContain('turn 1 was aborted')
    expect(agent.status).toBe('disposed')
  })

@@ -486,7 +490,7 @@ describe('formatTurnFailure', () => {
    const cases: [TurnEndReason, string][] = [
      [{ kind: 'completed' }, 'completed'],
      [{ kind: 'aborted' }, 'was aborted'],
-      [{ kind: 'aborted', reason: 'stop' }, 'was aborted: stop'],
+      [{ kind: 'aborted' }, 'was aborted'],
      [{ kind: 'error', step: 2, message: 'bad' }, 'failed at step 2: bad'],
      [{ kind: 'error', step: 3, failure: { message: 'provider bad', code: 'SERVER' } }, 'failed at step 3: provider bad'],
      [{ kind: 'disposed' }, 'was disposed'],
--- a/packages/examples/tui-demo/README.md
+++ b/packages/examples/tui-demo/README.md
@@ -29,6 +29,7 @@ Swappable LLM, bash, filesystem, and other capability providers remain in the le
 | `toolOrder` | lexicographic | Explicit model-facing tool order |
 | `tools` | owner default | Tool presentation mode |
 | `dshHome` | owner default | Harness home used by bash and skills |
+| `sessionTitle` | spine example limits | Fallback title word/byte limits |
 | `skills` | owner defaults | Skill registry, local provider, and tool config |
 | `toolBash` | owner defaults | Model-facing bash tool config |
 | `toolTasks` | owner defaults | Background-task control-tool config, or `false` |
--- 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
@@ -27,7 +27,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 {
@@ -45,12 +44,21 @@ export interface Config {
  tools?: ToolsConfig
  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
  dshHome?: string
+  /** Fallback session-title limits forwarded through agent-spine-demo. */
+  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  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. */
@@ -79,9 +87,11 @@ export const Config: z<Config> = z.object({
  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
  tools: ToolRegistry.Config,
  dshHome: z.string(),
+  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,
@@ -112,7 +122,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 },
@@ -52,7 +53,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[4]?.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[5]?.config as {
      readonly agents: Array<Record<string, unknown>>
@@ -88,7 +94,8 @@ describe('dsh-tui-demo app', () => {
    })

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