@songtonyli/dsh-cli 0.1.80 → 0.1.82

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/README.md +1 -1
  2. package/bin/dsh.mjs +1 -1
  3. package/node_modules/@aws-sdk/core/dist-cjs/submodules/protocols/index.js +94 -1589
  4. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/index.js +1 -7
  5. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/AwsJsonRpcProtocol.js +1 -3
  6. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/AwsRestJsonProtocol.js +1 -3
  7. package/node_modules/@aws-sdk/core/package.json +2 -2
  8. package/node_modules/@aws-sdk/credential-provider-env/package.json +3 -3
  9. package/node_modules/@aws-sdk/credential-provider-http/package.json +3 -3
  10. package/node_modules/@aws-sdk/credential-provider-ini/package.json +10 -10
  11. package/node_modules/@aws-sdk/credential-provider-login/package.json +4 -4
  12. package/node_modules/@aws-sdk/credential-provider-node/package.json +8 -8
  13. package/node_modules/@aws-sdk/credential-provider-process/package.json +3 -3
  14. package/node_modules/@aws-sdk/credential-provider-sso/package.json +5 -5
  15. package/node_modules/@aws-sdk/credential-provider-web-identity/package.json +4 -4
  16. package/node_modules/@aws-sdk/eventstream-handler-node/package.json +2 -2
  17. package/node_modules/@aws-sdk/middleware-eventstream/package.json +2 -2
  18. package/node_modules/@aws-sdk/middleware-websocket/package.json +3 -3
  19. package/node_modules/@aws-sdk/nested-clients/dist-cjs/submodules/cognito-identity/index.js +1 -1
  20. package/node_modules/@aws-sdk/nested-clients/dist-cjs/submodules/signin/index.js +1 -1
  21. package/node_modules/@aws-sdk/nested-clients/dist-cjs/submodules/sso/index.js +1 -1
  22. package/node_modules/@aws-sdk/nested-clients/dist-cjs/submodules/sso-oidc/index.js +1 -1
  23. package/node_modules/@aws-sdk/nested-clients/dist-cjs/submodules/sts/index.js +1 -1
  24. package/node_modules/@aws-sdk/nested-clients/package.json +3 -3
  25. package/node_modules/@aws-sdk/token-providers/dist-cjs/index.js +37 -19
  26. package/node_modules/@aws-sdk/token-providers/dist-es/fromSso.js +37 -19
  27. package/node_modules/@aws-sdk/token-providers/package.json +4 -4
  28. package/node_modules/@deepseek-ai/dsh-client-modules/lib/index.js +1 -1
  29. package/node_modules/@deepseek-ai/dsh-client-ui-sidebar/lib/client.js +1 -1
  30. package/node_modules/@deepseek-ai/dsh-subprocess-local/README.i18n.yaml +14 -14
  31. package/node_modules/@deepseek-ai/dsh-subprocess-local/README.md +7 -5
  32. package/node_modules/@deepseek-ai/dsh-subprocess-local/README.zh.md +7 -5
  33. package/node_modules/@deepseek-ai/dsh-subprocess-local/lib/index.js +15 -3
  34. package/node_modules/@deepseek-ai/dsh-subprocess-local/lib/runner-launch-f9xQyTek.js +1669 -0
  35. package/node_modules/@deepseek-ai/dsh-subprocess-local/lib/runner.js +1 -1
  36. package/node_modules/@deepseek-ai/dsh-tui-app/README.i18n.yaml +19 -16
  37. package/node_modules/@deepseek-ai/dsh-tui-app/README.md +30 -13
  38. package/node_modules/@deepseek-ai/dsh-tui-app/README.zh.md +30 -13
  39. package/node_modules/@deepseek-ai/dsh-tui-app/lib/index.js +615 -245
  40. package/node_modules/execa/lib/convert/duplex.js +8 -4
  41. package/node_modules/execa/lib/convert/readable.js +3 -8
  42. package/node_modules/execa/lib/convert/writable.js +6 -5
  43. package/node_modules/execa/lib/io/input-sync.js +2 -1
  44. package/node_modules/execa/lib/io/max-buffer.js +2 -1
  45. package/node_modules/execa/lib/io/output-sync.js +2 -1
  46. package/node_modules/execa/lib/methods/create.js +7 -0
  47. package/node_modules/execa/lib/methods/node.js +1 -1
  48. package/node_modules/execa/lib/methods/script.js +3 -3
  49. package/node_modules/execa/lib/resolve/all-async.js +2 -1
  50. package/node_modules/execa/lib/resolve/wait-subprocess.js +6 -0
  51. package/node_modules/execa/lib/stdio/handle-async.js +3 -2
  52. package/node_modules/execa/lib/stdio/handle.js +8 -3
  53. package/node_modules/execa/lib/transform/generator.js +7 -0
  54. package/node_modules/execa/lib/transform/run-sync.js +17 -5
  55. package/node_modules/execa/package.json +1 -1
  56. package/package.json +16 -16
  57. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/JsonSettings.js +0 -1
  58. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/codec-v1/JsonCodec.js +0 -20
  59. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/codec-v1/JsonSettings.js +0 -1
  60. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/codec-v1/JsonShapeDeserializer.js +0 -160
  61. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/codec-v1/JsonShapeSerializer.js +0 -193
  62. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/codec-v2/JsonBytesStringAdapter.js +0 -103
  63. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/codec-v2/JsonCodec2.js +0 -20
  64. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/codec-v2/JsonShapeDeserializer2.js +0 -200
  65. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/codec-v2/JsonShapeSerializer2.js +0 -519
  66. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/detectBufferParsing.js +0 -18
  67. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/jsonReplacer.js +0 -46
  68. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/jsonReviver.js +0 -121
  69. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/needsReviver.js +0 -41
  70. package/node_modules/@aws-sdk/core/dist-es/submodules/protocols/json/parseJsonBody.js +0 -89
@@ -1,4 +1,4 @@
1
- import { S as loadLinuxExecve, a as resolveWindowsExecutable, b as serializeRunnerError, f as consumeLinuxLaunchRequest, g as linuxLaunchFilesFromLocator, h as isWindowsTerminateRequest, i as parseRunnerTargetArgv, r as consumeRunnerSelection, t as SUBPROCESS_RUNNER_ENV, v as parseWindowsStartRequest, x as writeLinuxStartupError } from "./runner-launch-B2zsQ1Dz.js";
1
+ import { S as loadLinuxExecve, a as resolveWindowsExecutable, b as serializeRunnerError, f as consumeLinuxLaunchRequest, g as linuxLaunchFilesFromLocator, h as isWindowsTerminateRequest, i as parseRunnerTargetArgv, r as consumeRunnerSelection, t as SUBPROCESS_RUNNER_ENV, v as parseWindowsStartRequest, x as writeLinuxStartupError } from "./runner-launch-f9xQyTek.js";
2
2
  import { closeSync } from "node:fs";
3
3
  import { SUBPROCESS_CONTROL_FD } from "@deepseek-ai/dsh-subprocess/control";
4
4
  import { Win32Error, closeHandleChecked, isJobEmpty, loadWin32ProcessBindings, pollProcessExit, spawnCurrentTokenJobProcess, terminateJob } from "@deepseek-ai/dsh-win32-process";
@@ -18,14 +18,14 @@
18
18
  en: 192bbbb187278f91
19
19
  zh: 1f7e5632c15bdcf7
20
20
  /deepseek-ai-dsh-tui-app/use-this-package/starting-and-resuming:
21
- en: 58a8cf392bd6a90b
22
- zh: ff147492c5baf643
21
+ en: 312d9a3ea1cbb673
22
+ zh: 937ff76d6bdcca22
23
23
  /deepseek-ai-dsh-tui-app/use-this-package/the-screen:
24
- en: 365ce77bf78accd5
25
- zh: e945a1f209e18f36
24
+ en: 89282d4bb2afb533
25
+ zh: 40e9e9b14660fbef
26
26
  /deepseek-ai-dsh-tui-app/use-this-package/keys-and-commands:
27
- en: 8397ec35de157ed5
28
- zh: 135411de6c63f306
27
+ en: 381742ffd53e2298
28
+ zh: 745ab833542460ff
29
29
  /deepseek-ai-dsh-tui-app/use-this-package/background-tool-calls:
30
30
  en: 322ae3c6d76383ec
31
31
  zh: 8c38eee4b57ed8dd
@@ -36,17 +36,20 @@
36
36
  en: 2b7c7e8eb2b0281b
37
37
  zh: 1037fc8908901ccc
38
38
  /deepseek-ai-dsh-tui-app/use-this-package/references-and-attachments:
39
- en: 23ba736da2686f52
40
- zh: d30ce253dd934750
39
+ en: 253d589df7d691f0
40
+ zh: 94ec4cc098a033e8
41
+ /deepseek-ai-dsh-tui-app/use-this-package/quitting:
42
+ en: 1354f4f002a282eb
43
+ zh: 98ce0fa0ef7e3156
41
44
  /deepseek-ai-dsh-tui-app/use-this-package/configuration:
42
- en: 69b77811410fd6d6
43
- zh: 780fb134808e2d76
45
+ en: a49396b53b347ac4
46
+ zh: 6ee8443d318b2bf6
44
47
  /deepseek-ai-dsh-tui-app/understand-the-implementation:
45
48
  en: f124d406565fef39
46
49
  zh: 90344b5eec319cad
47
50
  /deepseek-ai-dsh-tui-app/understand-the-implementation/run-flow:
48
- en: 843f7f46161ca8d3
49
- zh: ddff3216005e2b57
51
+ en: a72d4dc0f5307a8a
52
+ zh: e4ec471d25470876
50
53
  /deepseek-ai-dsh-tui-app/understand-the-implementation/rendering-model:
51
54
  en: 42cc6ac3475fba61
52
55
  zh: 450342bc7b31cb61
@@ -54,8 +57,8 @@
54
57
  en: 142f04bf29e981dd
55
58
  zh: a1689297b06c9ca6
56
59
  /deepseek-ai-dsh-tui-app/understand-the-implementation/source-map:
57
- en: a1b526bb25bf3096
58
- zh: 36d8f8acc73700fd
60
+ en: d737dcab40a644f7
61
+ zh: f7bc1a1d254fd962
59
62
  /deepseek-ai-dsh-tui-app/understand-the-implementation/invariant-ownership:
60
63
  en: 0ddf6de8928026d5
61
64
  zh: 24feedcbb9e9d676
@@ -108,8 +111,8 @@
108
111
  en: 1dadc4a2f1560eaa
109
112
  zh: dc4697c269bc16b9
110
113
  /deepseek-ai-dsh-tui-app/known-limitations-and-deferred-work:
111
- en: 27275a2911d42533
112
- zh: 77b5a6bfd8b40ec9
114
+ en: 26e125a8a59bd810
115
+ zh: 63c9e3bd6e8a56a4
113
116
  /deepseek-ai-dsh-tui-app/known-limitations-and-deferred-work/dev-note:
114
117
  en: 5629c6159cec997f
115
118
  zh: 17f2d7e1f96da7f1
@@ -36,21 +36,21 @@ dsh tui --resume <session-id> # continue an earlier session
36
36
  dsh tui --no-open # print sign-in URLs without opening a browser
37
37
  ```
38
38
 
39
- On quit the app prints `dsh: session <id> saved; resume with: dsh --profile tui --resume <id>` on stderr for the session bound at that moment. A resumed session redraws its persisted history before accepting input and continues with that session's last model, or the launch default when the log has no request header; inside the terminal, `/resume` and `/sessions` open the same picker over persisted root sessions other than the current session, newest first, and resume the selected previous session, `/new` starts a fresh empty session with the launch default model, while `/clear` starts a fresh empty session that retains the current model and reasoning effort; the previous session stays on disk for `/resume`, and `/fork` copies the current session up to its last completed turn into a new one, the same cut the browser's fork takes. Switching releases the previous Agent and redraws the transcript of the next.
39
+ Once a quit has saved the session, the app prints `dsh: session <id> saved; resume with: dsh --profile tui --resume <id>` on stderr for the root session bound at that moment; [Quitting](#quitting) lists every line a quit prints. A resumed session redraws its persisted history before accepting input and continues with that session's last model, or the launch default when the log has no request header; inside the terminal, `/resume` and `/sessions` open the same picker over persisted root sessions other than the current session, newest first, and resume the selected previous session, `/new` starts a fresh empty session with the launch default model, while `/clear` starts a fresh empty session that retains the current model and reasoning effort; the previous session stays on disk for `/resume`, and `/fork` copies the current session up to its last completed turn into a new one, the same cut the browser's fork takes. Switching releases the previous Agent and redraws the transcript of the next.
40
40
 
41
41
  ### The screen
42
42
 
43
- Every frame is drawn one column in from each edge of the terminal, so no line of the conversation or of the docked chrome touches either side. The header names the session by its title once one is generated or set, with the id beside it. The transcript grows in the terminal's own scrollback: your prompts start with `❯` on a tinted full-width band while colour is on (attachments listed under them), and a prompt steered or injected into a turn that already had a model step draws dim on a darker band so it recedes behind the turn it joined, assistant reasoning is dim italic under a `✻ Thinking` header above the Markdown reply, a bloom spinning beside `Thinking` while it streams, and each tool call is a card with a status glyph — a yellow spinner of that tool family's flowers, blooms, and stars while it runs, a green `◆` once done, a red `◆` on failure — the bold tool name, the presenter headline in violet — without the tool name a presenter repeated, so `Read src/app.ts` draws as `read src/app.ts`, and for a shell card the call's own summary, never the command, which the card draws once as its `$` row — a loading row while it runs, and a body folded to `toolPreviewLines` rows. A top-level workflow call also draws its own run beside that card: the name, member count, status, and a ten-cell member progress bar with the settled count, then each phase and the members that started. While a live run runs, its `◇` pulses through a diamond animation and each running member's `○` spins in the subagent family's flowers, one phase ahead of the member before it; a run drawn from a replayed log spins only while its background job is still live, and reduced motion draws the static glyphs. Running groups and groups with a failed, cancelled, or interrupted member open; a clean completion stays closed. Space or Enter on a run or phase folds that level, and Enter on a running member opens its child only while that child is a live direct child of this session. The card appears when the model starts the call and flows out row after row, each row left to right, at one pace whatever the card holds: a full-width row takes `toolRevealFrames` frames, a shorter row proportionally less, and the columns just drawn brighten from the terminal background to their own colors. The result rows flow out the same way when the tool answers, behind whatever the card is still drawing; neither the call nor the result waits for the animation. An `edit` or `write` diff card fills each added row edge to edge with a green background and each removed row with a red one, the removed rows above the added ones, and paints the `+` and `-` in their own lighter colour so each sign reads against the fill rather than in it; a wrapped row carries the fill on without a second sign; once the tool applied the change, the applied hunks replace the diff the call carried and lead every row with its file line number, the new file's for added and unchanged rows and the old file's for removed rows. A `subagent` or `subagent_*` card draws folded as one row behind the same status glyph, spinning while it runs and a dim `◆` for a child handed to the background: while it runs, the tool name, the task description, and the requested model and `background` when the call names them; once settled, the description dimmed with `[done]`, `[started]` for a child handed to the background, or `[failed]` at the right edge. `Space` on the marked row, or `Ctrl+O`, unfolds the full card. A nonempty system prompt and each injected context — instructions, catalogs, snapshots, notices, relays, and recalls — draw as a dim `⬡` title over the first `contextPreviewLines` rows of their model-facing text, with each snapshot contribution named above its own rows; an empty system prompt is omitted. A compaction, from `/compact` or automatic, draws as one context block whose accent `⬡` title names its origin and the estimated tokens it replaced and its summary costs, as in `context compacted by /compact · ~6.4k → ~0.9k tokens` or `context compacted automatically in turn 12 · …`; under the title, `compressed` names the item count and turns the summary replaced, each prompt among them (five at most, one row each), and a count of the replies, tool results by tool, context blocks, and earlier summaries, and `preserved` names the system prompt and what each later turn still holds verbatim; both stay drawn while the summary under them folds to `contextPreviewLines` rows like any context block. The checkpoint message itself is not drawn again. A `/compact` attempt the log closes with an error prints `/compact failed · <error>` when the session is redrawn, since the live command reports its own failure; a failed automatic attempt changes nothing and draws nothing, as in the browser. A tool card and a context block that carry more rows than they draw end on one marker: `… <n> more rows · Space expands` while the conversation's focus holds that block, and `… <n> more rows · Ctrl+O expands` otherwise. Fenced code in a reply, the file rows of a `read` card, the changed rows of an `edit` or `write` diff card — with `+` additions marked green, `-` removals red, and source text behind those signs drawn in the language the file's extension names — and the shell command of a `!` / `!!` draft, a `$ command` user-shell row (its `$` in the accent colour), and a terminal tool card, use syntax colours from a theme the terminal's own background picks, light or dark; the grammar of a language loads on the first block that asks for it, so that block draws plain and is repainted in colour a moment later, and a language with no grammar here, a terminal that reports neither 24-bit nor 256 colours, and `codeHighlight: false` each draw every block plain. Headings and list markers use warm orange, links and inline code use violet, and quotes stay dim. Streamed reasoning, reply text, and tool arguments are queued as they arrive and drawn a share per frame, about 60 frames per second by default, so a network burst spreads over `streamPaceFrames` frames instead of landing at once, and the queue never holds the model call back. Streamed reply text fades in and every word keeps its own clock: a word enters near the terminal's background color and brightens to the color it settles in over `streamFadeSteps` ticks of `streamFadeStepMs` each, so a fast stream leaves a longer trail of brightening words rather than a darker one. Streamed reasoning floats out over the same duration: it appears at a lifted color and recedes to the dim italic it settles in. Each column of a tool card brightens over it from the terminal background to the palette color it settles in; a card redrawn from persisted history carries no flow or fade, and text that has settled is never dimmed again.
43
+ Every frame is drawn one column in from each edge of the terminal, so no line of the conversation or of the docked chrome touches either side. The header names the session by its title once one is generated or set, with the id beside it. The transcript grows in the terminal's own scrollback: your prompts start with `❯` on a tinted full-width band while colour is on (attachments listed under them), and a prompt steered or injected into a turn that already had a model step draws dim on a darker band so it recedes behind the turn it joined, assistant reasoning is dim italic under a `✻ Thinking` header above the Markdown reply, a bloom spinning beside `Thinking` while it streams, and each tool call is a card with a status glyph — a yellow spinner of that tool family's flowers, blooms, and stars while it runs, a green `◆` once done, a red `◆` on failure — the tool name in bold cyan, the presenter headline in teal — without the tool name a presenter repeated, so `Read src/app.ts` draws as `read src/app.ts`, and for a shell card the call's own summary, never the command, which the card draws once as its `$` row — a loading row while it runs, and a body folded to `toolPreviewLines` rows. A top-level workflow call also draws its own run beside that card: the name, member count, status, and a ten-cell member progress bar with the settled count, then each phase and the members that started. While a live run runs, its `◇` pulses through a diamond animation and each running member's `○` spins in the subagent family's flowers, one phase ahead of the member before it; a run drawn from a replayed log spins only while its background job is still live, and reduced motion draws the static glyphs. Running groups and groups with a failed, cancelled, or interrupted member open; a clean completion stays closed. Space or Enter on a run or phase folds that level, and Enter on a running member opens its child only while that child is a live direct child of this session. The card appears when the model starts the call and flows out row after row, each row left to right, at one pace whatever the card holds: a full-width row takes `toolRevealFrames` frames, a shorter row proportionally less, and the columns just drawn brighten from the terminal background to their own colors. The result rows flow out the same way when the tool answers, behind whatever the card is still drawing; neither the call nor the result waits for the animation. An `edit` or `write` diff card fills each added row edge to edge with a green background and each removed row with a red one, the removed rows above the added ones, and paints the `+` and `-` in their own lighter colour so each sign reads against the fill rather than in it; a wrapped row carries the fill on without a second sign; once the tool applied the change, the applied hunks replace the diff the call carried and lead every row with its file line number, the new file's for added and unchanged rows and the old file's for removed rows. A `subagent` or `subagent_*` card draws folded as one row behind the same status glyph, spinning while it runs and a dim `◆` for a child handed to the background: while it runs, the tool name, the task description, and the requested model and `background` when the call names them; once settled, the description dimmed with `[done]`, `[started]` for a child handed to the background, or `[failed]` at the right edge. `Space` on the marked row, or `Ctrl+O`, unfolds the full card. A nonempty system prompt and each injected context — instructions, catalogs, snapshots, notices, relays, and recalls — draw as a dim `⬡` title over the first `contextPreviewLines` rows of their model-facing text, with each snapshot contribution named above its own rows; an empty system prompt is omitted. A compaction, from `/compact` or automatic, draws as one context block whose accent `⬡` title names its origin and the estimated tokens it replaced and its summary costs, as in `context compacted by /compact · ~6.4k → ~0.9k tokens` or `context compacted automatically in turn 12 · …`; under the title, `compressed` names the item count and turns the summary replaced, each prompt among them (five at most, one row each), and a count of the replies, tool results by tool, context blocks, and earlier summaries, and `preserved` names the system prompt and what each later turn still holds verbatim; both stay drawn while the summary under them folds to `contextPreviewLines` rows like any context block. The checkpoint message itself is not drawn again. A `/compact` attempt the log closes with an error prints `/compact failed · <error>` when the session is redrawn, since the live command reports its own failure; a failed automatic attempt changes nothing and draws nothing, as in the browser. A tool card and a context block that carry more rows than they draw end on one marker: `… <n> more rows · Space expands` while the conversation's focus holds that block, and `… <n> more rows · Ctrl+O expands` otherwise. Fenced code in a reply, the file rows of a `read` card, the changed rows of an `edit` or `write` diff card — with `+` additions marked green, `-` removals red, and source text behind those signs drawn in the language the file's extension names — and the shell command of a `!` / `!!` draft, a `$ command` user-shell row (its `$` in the accent colour), and a terminal tool card, use syntax colours from a theme the terminal's own background picks, light or dark; the grammar of a language loads on the first block that asks for it, so that block draws plain and is repainted in colour a moment later, and a language with no grammar here, a terminal that reports neither 24-bit nor 256 colours, and `codeHighlight: false` each draw every block plain. Headings and list markers use orange, links and inline code use magenta, and quotes stay dim. Every hue is a Tokyo Night (Night) color, drawn exactly when `COLORTERM` declares `truecolor` or `24bit` and as the nearest of the 256 indexed colors otherwise; the background bands keep their 256-color greys and diff tints. Streamed reasoning, reply text, and tool arguments are queued as they arrive and drawn a share per frame, about 60 frames per second by default, so a network burst spreads over `streamPaceFrames` frames instead of landing at once, and the queue never holds the model call back. Streamed reply text fades in and every word keeps its own clock: a word enters near the terminal's background color and brightens to the color it settles in over `streamFadeSteps` ticks of `streamFadeStepMs` each, so a fast stream leaves a longer trail of brightening words rather than a darker one. Streamed reasoning floats out over the same duration: it appears at a lifted color and recedes to the dim italic it settles in. Each column of a tool card brightens over it from the terminal background to the palette color it settles in; a card redrawn from persisted history carries no flow or fade, and text that has settled is never dimmed again.
44
44
 
45
- Below the transcript sit a spinner while the agent works — `thinking`, `writing`, `calling <tool>`, a retry, or `compacting`, each beside its own braille animation: circling dots, filling lines, an orbiting dot, a sliding bar, or a settling cell — with a bright highlight sweeping across the word, plus live `↑` send and `↓` receive tokens for the current model call, as compact `k` / `M` / `B` counts, growing as the stream arrives and settling on the provider usage chunk — any open prompt, a boxed follow-ups list while messages wait, an activity board of the open turn's todos and latest descendant line while either has a row — completed todo content scratched out and status glyphs colored green, yellow, or cyan, the in-progress one a spinner, at most four todo rows then `+<n> more`, not a focus region, gone on `turn/end` and bind — the editor, the subagent panel, and the footer: a status bar that, unfocused, is one line built from both ends inward. The editor's caret is the terminal's own blinking bar: the app asks for that shape at start, gives your default back on quit, and draws no caret at all while the status bar or the panel holds the keyboard. The model and entry keys are colored; live turn, context, and todo facts use yellow, violet, and green. The model is anchored at the left edge and is never dropped — past 20 columns it falls back to the bare model name, and only a label still too wide for that is ellipsized — and the two keys that leave the input are anchored at the right edge as `Shift+↑ read · Shift+↓ status`, or `Shift+↑ select · Shift+↓ status` while follow-ups wait, narrowing to `Shift+↑↓ nav` and dropped below 40 columns. The key facts fill whatever middle is left, in bar order: effort (`effort default` when the selection leaves reasoning to the model), the running turn's elapsed time, the context window percentage, the todo counts, and the workspace path (shortened with `~` and `…/` when long). Every segment that middle cannot hold folds into a trailing `+N`, together with the segments the unfocused line never draws — the permission preset, token usage (session totals plus the in-flight call), the goal and plan-mode markers from the projection seam, and the count of pending attachments. Model-request retries appear as notices, the same facts the browser's markers carry.
45
+ Below the transcript sit a spinner while the agent works — `thinking`, `writing`, `calling <tool>`, a retry, or `compacting`, each beside its own braille animation: circling dots, filling lines, an orbiting dot, a sliding bar, or a settling cell — with a bright highlight sweeping across the word, plus live `↑` send and `↓` receive tokens for the current model call, as compact `k` / `M` / `B` counts, growing as the stream arrives and settling on the provider usage chunk — any open prompt, a boxed follow-ups list while messages wait, an activity board of the open turn's todos and latest descendant line while either has a row — completed todo content scratched out and status glyphs colored green, yellow, or blue, the in-progress one a spinner, at most four todo rows then `+<n> more`, not a focus region, gone on `turn/end` and bind — the editor, the subagent panel, and the footer: a status bar that, unfocused, is one line built from both ends inward. The editor's caret is the terminal's own blinking bar: the app asks for that shape at start, gives your default back on quit, and draws no caret at all while the status bar or the panel holds the keyboard. The model is purple and the entry keys magenta; live turn, context, and todo facts use yellow, magenta, and green. The model is anchored at the left edge and is never dropped — past 20 columns it falls back to the bare model name, and only a label still too wide for that is ellipsized — and the two keys that leave the input are anchored at the right edge as `Shift+↑ read · Shift+↓ status`, or `Shift+↑ select · Shift+↓ status` while follow-ups wait, narrowing to `Shift+↑↓ nav` and dropped below 40 columns. The key facts fill whatever middle is left, in bar order: effort (`effort default` when the selection leaves reasoning to the model), the running turn's elapsed time, the context window percentage, the todo counts, and the workspace path (shortened with `~` and `…/` when long). Every segment that middle cannot hold folds into a trailing `+N`, together with the segments the unfocused line never draws — the permission preset, token usage (session totals plus the in-flight call), the goal and plan-mode markers from the projection seam, and the count of pending attachments. Model-request retries appear as notices, the same facts the browser's markers carry.
46
46
 
47
47
  While the keyboard walks the conversation a framed inspector is docked directly above the editor, and the frame is the mode: it is drawn exactly while the conversation holds the keyboard. Its top rule carries an inverse ` ● READ ` chip and the focused section's heading — the section's position among the navigable blocks, the turn it belongs to, and what the section is — as in `╭ ● READ ─ 3/12 · turn 2 · bash git status · result ─╮`. Under it the block's parts draw as a numbered wrapping strip like `← 1 call · [2 result] →` when the block has more than one, the held label bracketed as well as accented so the selection is legible with no color at all; then the section's own source rows, each closed by a `│ ` border on both sides and wrapped four columns narrower, folded at `focusPreviewLines` for every section kind — a system prompt and an injected context included — with `… <n> more rows · Ctrl+G reads it` under them. The bottom rule carries the keys the conversation answers, `↑↓ sections · ←→ parts · Space folds · Ctrl+G reader · Esc input`, narrowed to `↑↓ ←→ · Space folds · Esc input` and then to `Esc input` as the terminal loses columns.
48
48
 
49
49
  The focused block is also marked where it stands, with a two-column gutter that is dim beside the block's other lines and accented beside the focused section's own — or beside the fold marker, when the fold left that section out of the drawn rows entirely — and its content wraps two columns narrower while the mark is drawn. That mark reaches only the lines pi-tui still repaints differentially — the last `rows` lines of the last frame it wrote, a window a taller frame raises and a shorter one never lowers — because changing anything above them would clear the terminal's scrollback. A block that has scrolled past that point keeps no gutter, the inspector heading appends ` · off screen`, and the frame's own rules draw dim instead of accent, so the frame itself reports that the mark cannot be drawn where the block stands. A fade whose rows reach that edge settles them to their final colors in the frame that writes them, so nothing stays dim in the scrollback.
50
50
 
51
- `Ctrl+G` from any region, `Enter` on a conversation section, and `/turns` read the conversation full screen, one turn at a time. The reader takes the terminal rather than drawing over the conversation: it runs on the terminal's alternate screen, the screen a pager runs on, and the conversation's own screen is held off the terminal for as long as it is up. So it costs the conversation no line, leaves the repaint window where it was, fills the screen on every terminal, and cannot leave a row of itself in your scrollback; closing it restores the conversation exactly as you left it, with whatever landed meanwhile drawn underneath. When the turn panel scrolls below its first row, a compact tinted bar replaces the top rule with the current user prompt, collapsed to one line and ellipsized to the terminal width; scrolling back to the top restores the ` ● READER ` chip and `turn <n> of <total>`. Under that fixed header, the turn being read takes most of the screen and a narrow turn list sits to its left, every body row closed by a right border. The list has one row per turn — `❯` on the turn being read, the turn number, the first line of its prompt, and right-aligned markers, `⬡<n>` injected context blocks, `✻` any reasoning, `¶` any reply, `◆<n>` tool calls — with the sections of the turn being read listed under it, `▸` on the one the reader holds, so any turn's own context is one step away. The turn panel scrolls that turn end to end in the conversation's own glyphs, a blank row between each two sections: the prompt opens it behind `❯` on a shaded band, then `✻ Thinking` in dim italic, `¶ Reply` rendered as the conversation renders Markdown — headings, emphasis, inline code, and fenced code in syntax colour — except that unordered bullets are drawn as `•`, a call's `◆` — green once its result landed, yellow while it runs — with the tool name in bold and its headline in the link blue, `⎿ Result` indented under its call with a diff's `+ ` rows green and `- ` rows red on shaded bands and a `read` card's file rows in syntax colour, and `⬡` with the label of an injected context. The section the top row belongs to is accented and carries the conversation walk's `┃` gutter on every row, which reads with no color at all. The bands are mixed from the background color the terminal reports, so a terminal that reports none, or draws no color, draws the panel without them. Rows are never folded there: the reader is where the full model-facing text of a system prompt, an injected snapshot, a long reply, or a tool result is read. `Right` opens the selected turn and `Left` goes back to the list; in the list `Up` / `Down` step one section at a time and cross into the turn either side while `PageUp` / `PageDown` step a whole turn, in the turn they scroll one row at a time, and the section the top row belongs to is where the conversation resumes when the reader closes. `/` opens a query line in place of the legend and narrows the list to the turns whose prompt or text matches, with the readout reading `<kept>/<total> turns`; otherwise the legend rule reports `turn 3/12 · row 14/212` at its right, which no width drops. Below `readerMinColumns` the body draws one panel at a time — the list, or the turn `Right` opens from it — and below 24 columns or 8 rows it draws one dim line, `terminal too small for the reader (needs 24×8)`, and answers only `Esc`, `Ctrl+G`, and `Ctrl+C`. It re-reads the conversation on every render, draws only sections in view, and reuses cached rows when their content, width, and styling match, so long turns stay responsive while the session runs; a streaming reply grows inside it, a landing tool result appears, and a new turn joins the list; a rewrap re-anchors on the section being read rather than on a row number; an approval or a question steps it aside for that prompt's lifetime; and a session switch takes it down with the notice `the transcript changed · reader closed`.
51
+ `Ctrl+G` from any region, `Enter` on a conversation section, and `/turns` read the conversation full screen, one turn at a time. The reader takes the terminal rather than drawing over the conversation: it runs on the terminal's alternate screen, the screen a pager runs on, and the conversation's own screen is held off the terminal for as long as it is up. So it costs the conversation no line, leaves the repaint window where it was, fills the screen on every terminal, and cannot leave a row of itself in your scrollback; closing it restores the conversation exactly as you left it, with whatever landed meanwhile drawn underneath. When the turn panel scrolls below its first row, a compact tinted bar replaces the top rule with the current user prompt, collapsed to one line and ellipsized to the terminal width; scrolling back to the top restores the ` ● READER ` chip and `turn <n> of <total>`. Under that fixed header, the turn being read takes most of the screen and a narrow turn list sits to its left, every body row closed by a right border. The list has one row per turn — `❯` on the turn being read, the turn number, the first line of its prompt, and right-aligned markers, `⬡<n>` injected context blocks, `✻` any reasoning, `¶` any reply, `◆<n>` tool calls — with the sections of the turn being read listed under it, `▸` on the one the reader holds, so any turn's own context is one step away. The turn panel scrolls that turn end to end in the conversation's own glyphs, a blank row between each two sections: the prompt opens it behind `❯` on a shaded band, then `✻ Thinking` in dim italic, `¶ Reply` rendered as the conversation renders Markdown — headings, emphasis, inline code, and fenced code in syntax colour — except that unordered bullets are drawn as `•`, a call's `◆` — green once its result landed, yellow while it runs — with the tool name in bold cyan and its headline in teal, `⎿ Result` indented under its call with a diff's `+ ` rows green and `- ` rows red on shaded bands and a `read` card's file rows in syntax colour, and `⬡` with the label of an injected context. The section the top row belongs to is accented and carries the conversation walk's `┃` gutter on every row, which reads with no color at all. The bands are mixed from the background color the terminal reports, so a terminal that reports none, or draws no color, draws the panel without them. Rows are never folded there: the reader is where the full model-facing text of a system prompt, an injected snapshot, a long reply, or a tool result is read. `Right` opens the selected turn and `Left` goes back to the list; in the list `Up` / `Down` step one section at a time and cross into the turn either side while `PageUp` / `PageDown` step a whole turn, in the turn they scroll one row at a time, and the section the top row belongs to is where the conversation resumes when the reader closes. `/` opens a query line in place of the legend and narrows the list to the turns whose prompt or text matches, with the readout reading `<kept>/<total> turns`; otherwise the legend rule reports `turn 3/12 · row 14/212` at its right, which no width drops. Below `readerMinColumns` the body draws one panel at a time — the list, or the turn `Right` opens from it — and below 24 columns or 8 rows it draws one dim line, `terminal too small for the reader (needs 24×8)`, and answers only `Esc`, `Ctrl+G`, and `Ctrl+C`. It re-reads the conversation on every render, draws only sections in view, and reuses cached rows when their content, width, and styling match, so long turns stay responsive while the session runs; a streaming reply grows inside it, a landing tool result appears, and a new turn joins the list; a rewrap re-anchors on the section being read rather than on a row number; an approval or a question steps it aside for that prompt's lifetime; and a session switch takes it down with the notice `the transcript changed · reader closed`.
52
52
 
53
- Transient key feedback floats as a dim framed line in the top-right corner of the viewport: `press Esc again to stop turn <n>`, `press Ctrl+C again to quit`, and `nothing in the transcript to read yet`. It holds at full strength for `toastMs`, fades out, costs the conversation no row of its own, and takes no keyboard; where the renderer can no longer repaint the top of the viewport it is printed into the conversation instead, which keeps it. Facts worth keeping are notices in the conversation: `stopping the turn…`, `wait for the session switch to finish`, `above the repaint window · opened in the reader`, and every command result.
53
+ Transient key feedback floats as a dim framed line in the top-right corner of the viewport: `press Esc again to stop turn <n>`, `press Ctrl+C again to quit` — `press Ctrl+C again to quit · stops 1 command, 2 background jobs` while commands, background jobs, or subagents run — and `nothing in the transcript to read yet`. It holds at full strength for `toastMs`, fades out, costs the conversation no row of its own, and takes no keyboard; where the renderer can no longer repaint the top of the viewport it is printed into the conversation instead, which keeps it. Facts worth keeping are notices in the conversation: `stopping the turn…`, `wait for the session switch to finish`, `above the repaint window · opened in the reader`, and every command result.
54
54
 
55
55
  Motion reaches past streamed text: every lift and float rides the same fade tick, and every working animation one spinner tick. The keyboard landing on the conversation, the subagent panel, or the status bar lifts that surface's frame, its chip, and the mark it holds for twelve ticks of `streamFadeStepMs`; a step of the conversation walk lifts the newly focused gutter for six; and a step along the bar lifts the selected label for eight. A new or status-changed activity-board todo row, and a replaced descendant line, float out on the fade tick; replay and `reducedMotion` draw the settled board. Every working animation has eight frames, takes the one it draws from the clock, and steps on the spinner tick of `spinnerMs`, 100 ms by default, so everything that spins advances at the same instant and speed, a label change keeps the beat, and the tick is armed only while one of them is drawn. The working spinner alone draws braille, its animation following its status, so it never repeats a card's glyph. A running tool card and a folded subagent row draw the animation of that tool's family, and an in-progress todo row draws the planning family's. Each of those animations mixes flowers, blooms, and stars, no two families share a glyph, and every frame of one family is different, so two indicators of one family at different phases never draw the same glyph. An indicator that starts while others of its family spin takes a phase at which it never draws their glyph at the same instant, for up to eight of that family spinning together; beyond eight, it takes the phase the fewest indicators of that family hold. A card whose header has scrolled above the part of the screen the renderer can repaint draws the static `◆` from then on, and `reducedMotion` draws every one of them still — the card's `◆`, the todo's `▸`, and the working spinner's label without a glyph — with no spinner tick. The reader arrives complete on the screen it owns, and what it newly shows floats out on the fade tick: opening it and showing another turn float out the whole turn, and stepping the list to another section of the same turn floats out that section, over `streamFadeSteps` ticks; scrolling, live growth, and a rewrap float nothing out. No lift changes how many lines anything draws, and `reducedMotion` — like `NO_COLOR`, a disabled palette, and `TERM=dumb` — turns every lift and float off and arms no repaint for them.
56
56
 
@@ -86,7 +86,7 @@ While the input has the keyboard:
86
86
  | `Ctrl+L` | Redraw the whole screen from scratch |
87
87
  | `?` | On an empty input, list the commands and keys, like `/help`; inside a draft it is typed |
88
88
  | `Esc` | Cancel a running `!` or `/compact`; with a leading `!` draft and no turn running, clear the editor; otherwise arm the stop, and a second press while that line is on screen stops the running turn |
89
- | `Ctrl+C` | Clear the editor; a second press within 600 ms quits |
89
+ | `Ctrl+C` | Clear the editor and arm the quit; a second press while the `press Ctrl+C again to quit` line is on screen quits |
90
90
  | `Ctrl+D` | Quit when the editor is empty |
91
91
 
92
92
  An `Esc` that only handed the keyboard back — leaving a region, closing a page, a picker, or the reader — opens a 750 ms window in which an `Esc` reaching the input does nothing at all, so a habitual double press stops no turn. With no turn running, `Esc` closes the completion list while one is open, clears a draft that starts with `!`, and is silent otherwise. A session with nothing to read yet answers `Shift+Up` (when no follow-up waits) and `Ctrl+G` with `nothing in the transcript to read yet` and leaves the keyboard in the input.
@@ -190,7 +190,7 @@ Typing `/` at the start of the editor completes the terminal's own commands and
190
190
  | `/login` | Sign in with a provider subscription (hides key-collecting logins); `/login <key>` skips the picker |
191
191
  | `/export [dir]` | Write this session's log ZIP (sub-sessions and attachments included) into `dir`, default the workspace |
192
192
  | `/status` | Context window usage and breakdown, token totals with cache hit, session stats, todos, goal, plan mode, and permission |
193
- | `/context` | How the context window is used right now: a grid of 200 cells beside the model, the occupancy, and the estimated tokens of the system prompt, tool definitions, instruction files, skills, other injected context, and messages, then the free space. The cells holding the tokens the newest turn added are the hot region, drawn bold and counted on the `▲ hot` row. Where the terminal runs motion, the grid fills on open and a bright band sweeps through the hot region; while a turn runs the report re-reads the usage every quarter second, marks itself `live`, and blinks the first free cell. It settles once no turn runs and its open animation ended, when another `/context` opens, on a session switch, or once it leaves the repaint window. Reduced motion draws only the settled report |
193
+ | `/context` | How the context window is used right now: a grid of 200 cells beside the model, the occupancy, and the estimated tokens of the system prompt, tool definitions, instruction files, skills, other injected context, and messages, then the free space. Each category draws its cells in its own hue — system blue, tools cyan, instructions orange, skills yellow, other context green, and messages magenta. The cells holding the tokens the newest turn added are the hot region, drawn bold and counted on the `▲ hot` row. Where the terminal runs motion, the grid fills on open and a bright band sweeps through the hot region; while a turn runs the report re-reads the usage every quarter second, marks itself `live`, and blinks the first free cell. It settles once no turn runs and its open animation ended, when another `/context` opens, on a session switch, or once it leaves the repaint window. Reduced motion draws only the settled report |
194
194
  | `/todos` | Browse the agent's todo list; completed rows are scratched out; `Enter` opens one item in full with its status, position, and turns |
195
195
  | `/outline` | The turns of this session with their prompt and reply previews |
196
196
  | `/deliverables` | The files the agent presented, grouped by turn |
@@ -228,6 +228,18 @@ An approval request draws `Allow <tool>?` with the asker's reason, the logged ca
228
228
 
229
229
  `@` followed by text lists matching files and directories — workspace-relative, `../` from the workspace, `~/` from the home directory, or absolute — and other sessions, in the same mention grammar the browser composer inserts (`@path`, `@"path with spaces"`, and the opaque `@[label](…)` session token); the base rows resolve those mentions into the prompt exactly as they do for the browser. `/attach <path>` reads a local file relative to the workspace and stores it through the composed attachment store, as an image block for `.png`, `.jpg`, `.jpeg`, `.webp`, and `.gif` and as a file block otherwise; pending attachments travel with the next prompt and are listed under it.
230
230
 
231
+ <a id="quitting"></a>
232
+ ### Quitting
233
+
234
+ `Ctrl+C` twice, `Ctrl+D` on an empty input, `/quit`, and `/exit` quit; the second `Ctrl+C` must arrive while `press Ctrl+C again to quit` is on screen, and any other key in between disarms the first. A quit counts the commands, background jobs, and subagents running under the root session, stops a running `!` command, and hands the terminal back to your shell. It then stops the rest in order: it cancels the running turn, which stops the model's commands, waits for the agent to go idle, saves the session log, and releases the session, which stops its background jobs and subagents. A failed step does not skip the steps after it. Meanwhile the app writes to stderr:
235
+
236
+ - `dsh: stopping <work> (Ctrl+C to force)` when anything runs, where `<work>` reads like `1 command, 2 background jobs, 1 subagent`, then `dsh: still stopping <work> (Ctrl+C to force)` every 2 s, naming what still runs.
237
+ - `dsh: gave up waiting after <N>s; <work> may still be running` when the stop outlasts `quitGraceMs`, and `dsh: forcing exit; <work> may still be running` when `Ctrl+C` ends the wait; either line omits `; <work> may still be running` when nothing still runs.
238
+ - `dsh: saving the session failed: <reason>` or `dsh: stopping failed: <reason>` for each failed step.
239
+ - `dsh: session <id> saved; resume with: dsh --profile tui --resume <id>` last, whenever the session log was saved.
240
+
241
+ The exit code is 130 when `Ctrl+C` ended the wait, 129 when the terminal closed, 1 when the wait gave up or a step failed, and 0 otherwise. `quitGraceMs` (default 10000 ms, at least 1000) bounds the whole stop; after it, the launcher's own disposal waits at most 5 s more and kills the command processes still running as the process exits. Closing the terminal sends `SIGHUP`, which runs the same stop; output to the closed terminal is dropped. A process that a command detached from its own process tree can outlive the quit; see [Known Limitations and Deferred Work](#known-limitations-and-deferred-work).
242
+
231
243
  ### Configuration
232
244
 
233
245
  | Field | Default | Meaning |
@@ -239,7 +251,8 @@ An approval request draws `Allow <tool>?` with the asker's reason, the logged ca
239
251
  | `focusPreviewLines` | `12` | Rows of the focused section the docked inspector shows before its fold marker sends the rest to the reader, for every section kind |
240
252
  | `readerMinColumns` | `60` | Columns the reader needs before it draws the selected turn beside the turn list; below it one panel is drawn at a time |
241
253
  | `codeHighlight` | `true` | Draw fenced code in a reply, the file rows of `read` and diff tool cards, and shell commands in a `!` / `!!` draft, a `$ command` row, and a terminal tool card, in syntax colours, from a theme the terminal's background picks |
242
- | `toastMs` | `2000` | How long a transient key-feedback line holds at full strength before it fades out, which is also the window in which a second `Esc` stops the running turn |
254
+ | `toastMs` | `2000` | How long a transient key-feedback line holds at full strength before it fades out; while the line is on screen, a second `Esc` stops the running turn and a second `Ctrl+C` quits |
255
+ | `quitGraceMs` | `10000` | How long a quit waits for the running turn to stop, the session log to save, and the session's background jobs and subagents to stop before it names what may still run and exits with code 1; the launcher's own 5 s disposal follows. A value below 1000 is rejected |
243
256
  | `liveRefreshMs` | `1000` | Period of the redraw that advances the `turn` segment and the panel's elapsed values and re-reads a stale subagent listing |
244
257
  | `streamFadeSteps` | `24` | How many ticks a fade lasts: reply text and the columns of a tool card fade in, reasoning floats out, over `streamFadeSteps × streamFadeStepMs` |
245
258
  | `streamFadeStepMs` | `16` | One frame: the fade tick, the repaint period while anything is still moving, and the period paced stream text is drawn at; duration is `streamFadeSteps × streamFadeStepMs` |
@@ -266,7 +279,7 @@ The runner is a direct driver over the core API carrier, like `dsh-headless`, th
266
279
 
267
280
  ### Run flow
268
281
 
269
- The runner awaits the complete application (`ctx.get('loader')?.await()`) and builds a session host over the core registry with five operations: `create` makes one fresh persisted Agent with its requested selection or the shared [`agentDefaultModel`](../../core/agent-default-model/README.md) selection, `resume` takes the Agent write handle first and then observes the live Session through `ctx.sessionQuery` so bind draws every persisted event including resume closers, and `fork` observes the source through `ctx.sessionQuery`, cuts after the chosen (by default the last) `turn/end` up to the next `turn/start`, and creates a seeded Agent with `parentSession` and `isSeeded` metadata, and `observe` opens a subagent session without releasing the bound one — a resident subagent Agent is read live and its release does nothing, and any other session is resumed, and `aside` creates a `/btw` side agent seeded through `buildForkSeed` with the bound session's whole log as `ctx.sessionQuery` observes it, recording `parentSession`, `isSeeded`, and `origin: 'subagent'` but passing no parent Agent and appending no catalog event to the parent, then in its setup appends the `read-only` sandbox mode and the `never` approval policy and restricts its global tools to the configured names. Every operation except a resident `observe` installs a `ModelSelectionRef` in the Agent's scoped setup so `/model` changes the next request; `resume` passes the launch default as AgentOptions so assemble has a `{{model}}` value, then overlays the log's last request header onto the selection when one exists, else keeps that default. The terminal application starts on the session `--resume` or a fresh `create` yields, subscribes to `session/event`, `agent/assistant-stream`, and `agent/status`, answers the `approval/request` and `user-questions/request` waterfalls for the bound Agent and for every session a view is held open over, and switches sessions by binding the next one and disposing the previous handle; while the host opens the next session the editor refuses input, and a quit during that wait releases the session that arrives afterwards. Quitting cancels any running turn, waits for quiescence, flushes the bound Session, disposes its handle, and requests exit 0; a driver failure writes `dsh: <message>` to stderr and requests exit 1. `/resume` and `/sessions` share the persisted-session chooser. Editor `Shift+Tab` dispatches empty `/effort` to open its current-model picker, and editor `Shift+Left` / `Shift+Right` use pi-tui's word navigation. `/login` starts `authorization.begin` with only subscription methods (every method except a key-collecting `api-key` login). A notice the flow marks with `openInBrowser` is handed to the default browser through `dsh-native-command`'s credential-scrubbed helper while the URL stays printed; the handoff is suppressed when `openBrowser` is false, the launch came through SSH, or the host has no desktop, and an opener failure becomes a notice beside the URL rather than a sign-in failure. A nonempty `!` or `!!` line submitted in the editor runs through `ctx.shell` in this process; `!` injects a next-step notice and `!!` stays local.
282
+ The runner awaits the complete application (`ctx.get('loader')?.await()`) and builds a session host over the core registry with five operations: `create` makes one fresh persisted Agent with its requested selection or the shared [`agentDefaultModel`](../../core/agent-default-model/README.md) selection, `resume` takes the Agent write handle first and then observes the live Session through `ctx.sessionQuery` so bind draws every persisted event including resume closers, and `fork` observes the source through `ctx.sessionQuery`, cuts after the chosen (by default the last) `turn/end` up to the next `turn/start`, and creates a seeded Agent with `parentSession` and `isSeeded` metadata, and `observe` opens a subagent session without releasing the bound one — a resident subagent Agent is read live and its release does nothing, and any other session is resumed, and `aside` creates a `/btw` side agent seeded through `buildForkSeed` with the bound session's whole log as `ctx.sessionQuery` observes it, recording `parentSession`, `isSeeded`, and `origin: 'subagent'` but passing no parent Agent and appending no catalog event to the parent, then in its setup appends the `read-only` sandbox mode and the `never` approval policy and restricts its global tools to the configured names. Every operation except a resident `observe` installs a `ModelSelectionRef` in the Agent's scoped setup so `/model` changes the next request; `resume` passes the launch default as AgentOptions so assemble has a `{{model}}` value, then overlays the log's last request header onto the selection when one exists, else keeps that default. The terminal application starts on the session `--resume` or a fresh `create` yields, subscribes to `session/event`, `agent/assistant-stream`, and `agent/status`, answers the `approval/request` and `user-questions/request` waterfalls for the bound Agent and for every session a view is held open over, and switches sessions by binding the next one and disposing the previous handle; while the host opens the next session the editor refuses input, and a quit during that wait releases the session that arrives afterwards. Quitting runs the sequence in `src/quit.ts` over the root binding: it cancels any running turn, waits for quiescence, flushes the root Session, and disposes its handle, each step contained so a failure does not skip the next, races that sequence against `quitGraceMs` and a `SIGINT` listener registered only while the quit runs, and then writes the outcome lines and requests the exit code the report maps to; a `SIGHUP` listener the runner registers as an effect runs the same quit with the terminal treated as gone. A driver failure writes `dsh: <message>` to stderr and requests exit 1. `/resume` and `/sessions` share the persisted-session chooser. Editor `Shift+Tab` dispatches empty `/effort` to open its current-model picker, and editor `Shift+Left` / `Shift+Right` use pi-tui's word navigation. `/login` starts `authorization.begin` with only subscription methods (every method except a key-collecting `api-key` login). A notice the flow marks with `openInBrowser` is handed to the default browser through `dsh-native-command`'s credential-scrubbed helper while the URL stays printed; the handoff is suppressed when `openBrowser` is false, the launch came through SSH, or the host has no desktop, and an opener failure becomes a notice beside the URL rather than a sign-in failure. A nonempty `!` or `!!` line submitted in the editor runs through `ctx.shell` in this process; `!` injects a next-step notice and `!!` stays local.
270
283
 
271
284
  ### Rendering model
272
285
 
@@ -280,11 +293,12 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
280
293
 
281
294
  | File | Role |
282
295
  |---|---|
283
- | [`src/index.ts`](src/index.ts) | The `tui-app` plugin: the session host (create, resume, fork, observe), resume observation, quit flow, exit mapping |
296
+ | [`src/index.ts`](src/index.ts) | The `tui-app` plugin: the session host (create, resume, fork, observe), resume observation, and the quit wiring: the `SIGHUP` and `SIGINT` listeners, the budget, the outcome lines, and the exit request |
297
+ | [`src/quit.ts`](src/quit.ts) | The quit sequence: the census of running work and its wording, the ordered, contained, and bounded stop, and the stderr lines and exit code a report maps to |
284
298
  | [`src/resume-model.ts`](src/resume-model.ts) | Resume-time model selection from the last request header or the launch default |
285
299
  | [`tests/resume-model.spec.ts`](tests/resume-model.spec.ts) | Resume restores the last logged route, else the launch default |
286
300
  | [`src/startup.ts`](src/startup.ts) | The `tui-app-startup` provider: prompt positional, `--resume`, `--no-open`, and `--help` |
287
- | [`src/app.ts`](src/app.ts) | The terminal application: layout, the key router, commands, session binding, seams, log and stream folding, the activity board above the editor, the stop arm, the transient line it mounts, the terminal handover the reader runs on, and prefix-on-submit `!` / `!!` |
301
+ | [`src/app.ts`](src/app.ts) | The terminal application: layout, the key router, commands, session binding, seams, log and stream folding, the activity board above the editor, the stop and quit arms, the census of the work a quit stops, the transient line it mounts, the terminal handover the reader runs on, and prefix-on-submit `!` / `!!` |
288
302
  | [`src/keys.ts`](src/keys.ts) | The key model: the focus regions, what one press means in each, the legends they degrade through, the entry keys, the `/help` lines, and the handoff window |
289
303
  | [`src/sessions.ts`](src/sessions.ts) | The persisted-session list and picker rows shared by `/resume` and `/sessions`; titles come from the live or cached title projection |
290
304
  | [`src/effort.ts`](src/effort.ts) | Reasoning-effort names and picker rows shared by `/model`, `/effort`, and editor `Shift+Tab` |
@@ -315,7 +329,7 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
315
329
  | [`src/pinned-prompt.ts`](src/pinned-prompt.ts) | The prompt row the reader pins over a scrolled turn: the glyph, the prompt collapsed to one line, and the band |
316
330
  | [`src/transcript.ts`](src/transcript.ts) | Pure text folding of presentation views, usage, and turn-end reasons, the `$ command` span, and the one fold grammar every marker is written in |
317
331
  | [`src/diff.ts`](src/diff.ts) | Line diff, hunk selection, and the addition and removal marks diff cards box |
318
- | [`src/style.ts`](src/style.ts) | The palette, including the cool dark-mode heading and link hues a Markdown reply uses, the strikethrough role completed todo content uses, the background band a prompt is drawn on and the darker one a steered or injected prompt is drawn on, the green and red fills and sign colours of a diff card's changed rows, whether key chips are clickable, and the derived pi-tui themes |
332
+ | [`src/style.ts`](src/style.ts) | The palette: the Tokyo Night hues as truecolor or 256-color SGR, the semantic roles drawn in them — including the heading and link hues a Markdown reply uses and the tool-name, call-subject, and model hues — the strikethrough role completed todo content uses, the background band a prompt is drawn on and the darker one a steered or injected prompt is drawn on, the green and red fills and sign colours of a diff card's changed rows, whether key chips are clickable, and the derived pi-tui themes |
319
333
  | [`src/highlight.ts`](src/highlight.ts) | Syntax colour for fenced code, file rows, and shell commands: the grammars a block may load, the theme the background picks, and the SGR one token is drawn with |
320
334
  | [`src/completion.ts`](src/completion.ts) | Slash-command and `@`-reference completion for the editor |
321
335
  | [`src/editor.ts`](src/editor.ts) | The prompt editor's terminal caret, its `Shift+Left` / `Shift+Right` mapping to pi-tui word navigation, and syntax colour on a `!` / `!!` draft |
@@ -332,7 +346,7 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
332
346
  | [`src/todos.ts`](src/todos.ts) | The todo list: the status glyphs, the picker rows with completed content scratched out, and one item's detail rows |
333
347
  | [`cordis.patch.yml`](cordis.patch.yml) | The terminal patch over `dsh-base` |
334
348
  | — | No runtime invariant companion is published; the app registers listeners on one Agent and holds no mutable relation another observer could contradict. |
335
- | [`tests/app.spec.ts`](tests/app.spec.ts) | Rendering, keys, commands, the stop arm, the follow-ups rows above the editor, the activity board, and both seams over a fake terminal |
349
+ | [`tests/app.spec.ts`](tests/app.spec.ts) | Rendering, keys, commands, the stop and quit arms, the follow-ups rows above the editor, the activity board, and both seams over a fake terminal |
336
350
  | [`tests/background.spec.ts`](tests/background.spec.ts) | `Ctrl+B` over the real tool runtime, job registry, and job tools: the spinner hint, the moved result and card, the jobs line, `/jobs` output and `Ctrl+K`, completion notices, refusal, failure, and the turn stop |
337
351
  | [`tests/background-tracking.spec.ts`](tests/background-tracking.spec.ts) | Which calls the wrapper tracks, which jobs count as a call's own, and the moved-result text |
338
352
  | [`tests/jobs-panel.spec.ts`](tests/jobs-panel.spec.ts) | The jobs line, `/jobs` rows, detail page, and settlement line as text |
@@ -366,10 +380,12 @@ The patch rides over `dsh-base`: it sets the coding persona prefix and cwd suffi
366
380
  | [`tests/compaction-app.spec.ts`](tests/compaction-app.spec.ts) | `/compact` in the terminal: the spinner, `Esc`, queued prompts, the refused switch, the block in place of the result, and the block from a replayed log |
367
381
  | [`tests/sessions.spec.ts`](tests/sessions.spec.ts) | Session picker listing: newest first, live or cached titles, hidden subagents |
368
382
  | [`tests/index.spec.ts`](tests/index.spec.ts) | Creation, resume paging, resume model assembly, fork cut, session switching, quit flow, and failure reporting |
383
+ | [`tests/quit.spec.ts`](tests/quit.spec.ts) | The quit order, the budget, the force, contained step failures, the progress notices, and the lines and exit code each outcome maps to |
369
384
  | [`tests/startup.spec.ts`](tests/startup.spec.ts) | Command-line parsing over a real Loader tree |
370
385
  | [`tests/shortcuts.spec.ts`](tests/shortcuts.spec.ts) | `?` on an empty input and inside a draft, `Ctrl+T` from any region, `Ctrl+P` at the root session, and the `Ctrl+L` redraw |
371
386
  | [`tests/subagents.spec.ts`](tests/subagents.spec.ts) | The live subagent panel's rows, walk, and listing refresh, and the subagent view it and `/subagents` open, left through `/parent` and `Ctrl+P` and released on a session switch and on quit |
372
387
  | [`../../../apps/cli/tests/profiles/tui/tests/keyless-smoke.e2e.ts`](../../../apps/cli/tests/profiles/tui/tests/keyless-smoke.e2e.ts) | The shipped profile through the real launcher with a keyless mock model |
388
+ | [`../../../apps/cli/tests/profiles/tui/tests/quit-while-busy.e2e.ts`](../../../apps/cli/tests/profiles/tui/tests/quit-while-busy.e2e.ts) | The shipped profile quitting while a command, a background job, a subagent, or a process that ignores `SIGTERM` is running, and on `SIGHUP` and `SIGINT`: the stderr lines and their order, the exit codes, and that no process survives |
373
389
 
374
390
  ### Invariant ownership
375
391
 
@@ -479,6 +495,7 @@ These limits describe the terminal surface as shipped; they are not a general CL
479
495
  - **Clicks need the terminal's cooperation** — with `mouse: true` the terminal's mouse reports are on for the whole run, so the wheel and plain click-drag stop scrolling its scrollback and selecting text unless `Shift` is held; a click on the main screen is placed by the terminal's answer to a cursor-position query, so a terminal that never answers ignores clicks there, while the reader's screen needs no answer; and a chip in scrollback the terminal is scrolled back through cannot be clicked, because the mouse report names a row of the live screen.
480
496
  - **The terminal's own caret can flicker** — the editor draws no caret of its own and the app turns the terminal cursor on, which pi-tui then moves across the lines it repaints; a terminal that does not honor the synchronized-output sequences pi-tui wraps a frame in can show that movement.
481
497
  - **Runs through the `dsh` launcher** — starting the profile another way fails at startup, because only the launcher can request the process exit.
498
+ - **A command's detached processes can outlive a quit** — on macOS, and on Linux without a usable user-systemd scope, a quit stops each running command's process group and the descendants still under the command in the process tree, but a process that double-forked away from it (re-parented to process 1) is not tracked and keeps running; Linux native mode keeps such processes in the command's scope. The [subprocess-local limitations](../../subprocess/subprocess-local/README.md#known-limitations-and-deferred-work) describe the containment each platform provides.
482
499
  - **A `/btw` side agent is read-only by tool name and sandbox** — `btwTools` must name only tools that read, because the side agent shares the workspace with the working agent; a command tool can read anything the `read-only` sandbox mode allows, and without a confining command executor command tools are hidden. It inherits only what the working session has logged: reply text still streaming is absent. Its log is stored like a subagent session's and hidden from `/resume` and `/sessions`, and Web has no `/btw`.
483
500
  - **A moved call stays tied to its turn and returns text** — the tool runtime fuses the turn's signal into every call, so `Esc` on the turn that dispatched a call stops it even after `Ctrl+B`; a job result is a string, so other content blocks of the call's result are named as `[image omitted]` and the like; and moving needs `ctx.jobs` with `dsh-tool-jobs`, which the base profile composes.
484
501
  - **Workflow runs show identity and status** — a top-level workflow call draws a run beside its tool card: the name, member count, status, progress, phases, and started members. `/workflows` stops only a background run; a run inside the turn stops with the turn. Running and abnormal groups open; a clean completion stays closed. Space or Enter on a run or phase folds that level. Enter opens a running member only while it is a live direct child of this session, and does not resume a member that has finished. The script stays on the tool card. A background run stays running after its launch turn while its job is live; an unfinished run with no live job is interrupted on replay. Phase and log lines stay on `/jobs`, and the job's return value stays with `job_output`.
@@ -36,21 +36,21 @@ dsh tui --resume <session-id> # continue an earlier session
36
36
  dsh tui --no-open # print sign-in URLs without opening a browser
37
37
  ```
38
38
 
39
- 退出时应用在 stderr 为当时绑定的会话打印 `dsh: session <id> saved; resume with: dsh --profile tui --resume <id>`。恢复的会话会在接受输入前先重绘其持久化历史,并沿用该会话上次使用的模型;日志里还没有请求头时则使用启动默认模型。在终端内,`/resume` 与 `/sessions` 打开同一个选择器,按从新到旧列出当前会话以外的持久化根会话,并恢复选中的先前会话,`/new` 使用启动默认模型开始新的空会话,而 `/clear` 开始新的空会话并保留当前模型和推理强度;先前会话仍留在磁盘上可用 `/resume` 恢复,`/fork` 把当前会话复制到其最后一个完成轮次并作为新会话,切割点与浏览器的 fork 相同。切换会释放先前的 Agent 并重绘下一个会话的对话记录。
39
+ 一次退出保存会话之后,应用在 stderr 为当时绑定的根会话打印 `dsh: session <id> saved; resume with: dsh --profile tui --resume <id>`;[退出](#quitting)列出退出时打印的每一行。恢复的会话会在接受输入前先重绘其持久化历史,并沿用该会话上次使用的模型;日志里还没有请求头时则使用启动默认模型。在终端内,`/resume` 与 `/sessions` 打开同一个选择器,按从新到旧列出当前会话以外的持久化根会话,并恢复选中的先前会话,`/new` 使用启动默认模型开始新的空会话,而 `/clear` 开始新的空会话并保留当前模型和推理强度;先前会话仍留在磁盘上可用 `/resume` 恢复,`/fork` 把当前会话复制到其最后一个完成轮次并作为新会话,切割点与浏览器的 fork 相同。切换会释放先前的 Agent 并重绘下一个会话的对话记录。
40
40
 
41
41
  ### 屏幕布局
42
42
 
43
- 每一帧都从终端左右两边各内缩一列绘制,因此对话记录与停靠的界面组件都不会有任何一行贴到两侧边缘。页眉在标题生成或设置后以标题命名会话,并在旁边显示 id。对话记录在终端自身的回滚区中增长:你的提示以 `❯` 开头,启用颜色时铺在一条通栏的着色背景带上(附件列在其下),而在已有模型步骤的轮次中被引导或注入的提示以暗色文字铺在更深的背景带上,退到它所加入的轮次之后,assistant 的推理以暗色斜体显示在 `✻ Thinking` 标题之下、Markdown 回复上方,流式期间标题旁的绽放符号随之旋转,每次工具调用是一张卡片,含状态符号(运行中为按工具族混合花朵、绽放与星形的黄色旋转指示、完成为绿色 `◆`、失败为红色 `◆`)、粗体工具名、以紫色显示的呈现器标题(去掉呈现器重复写出的工具名,因此 `Read src/app.ts` 画成 `read src/app.ts`;shell 卡片取该次调用自身的摘要,绝不取命令,命令只由卡片的 `$` 行绘制一次)、运行中的一行加载标记,以及折叠到 `toolPreviewLines` 行的正文。顶层 workflow 调用还会在该卡片旁另绘一次运行:运行名、成员数、状态,以及一条十格的成员进度条与已结束数,然后是每个阶段和已启动的成员。实时运行进行中时,其 `◇` 以菱形动画脉动,每个运行中成员的 `○` 以子 agent 族的花朵旋转,相位比前一个成员领先一格;从重放日志绘制的运行只在其后台作业仍存活时旋转,减少动效时绘制静态符号。运行中的层级,以及含失败、取消或中断成员的层级会展开;干净完成的层级保持折叠。在运行或阶段上按 Space 或 Enter 折叠该层,在仍在运行的成员上按 Enter 只会在该子会话是本会话的直接子会话且仍在本进程运行时打开它。卡片在模型开始调用时出现,并逐行向外流出,每行从左到右,无论卡片装着什么,速度都一致:一整行宽的内容需 `toolRevealFrames` 帧,较短的行按比例更短,刚画出的列会从终端背景色亮起到各自的颜色。工具回答后,结果行也以同样方式流出,排在卡片尚未画完的内容之后;调用与结果都不会等待动画。`edit` 或 `write` diff 卡片把每一新增行整行铺满绿色背景、每一删除行整行铺满红色背景,删除的旧行在上、新增的新行在下,并把 `+` 与 `-` 画成各自更亮的颜色,使符号从填充色中读得出来;折行续行只延续填充色,不再画第二个符号;工具应用变更后,已应用的 hunk 取代调用时携带的 diff,并在每行前标出文件行号,新增行与未变行用新文件的行号,删除行用旧文件的行号。`subagent` 与 `subagent_*` 卡片折叠时只画一行,行首是同样的状态符号,运行中旋转,交给后台的子 agent 则为暗色 `◆`:运行中显示工具名、任务描述,以及调用指定的模型与 `background`;结束后描述变暗,右端标出 `[done]`,交给后台的子 agent 标 `[started]`,失败标 `[failed]`。在被标记的行上按 `Space`,或按 `Ctrl+O`,即可展开完整卡片。非空的系统提示词与每一条注入的上下文——instructions、catalogs、snapshots、notices、relays 与 recalls——绘制为暗色 `⬡` 标题,其下是面向模型文本的前 `contextPreviewLines` 行,快照的每一份贡献具名写在其自身各行上方;空的系统提示词则省略。一次压缩(compaction)——无论来自 `/compact` 还是自动触发——绘制为一个上下文块,其强调色 `⬡` 标题写明来源,以及被替换内容与摘要各自的估算 token 数,如 `context compacted by /compact · ~6.4k → ~0.9k tokens` 或 `context compacted automatically in turn 12 · …`;标题之下,`compressed` 写明摘要替换的条目数与轮次、其中的每条提示(最多五条,每条一行),以及回复、按工具分列的工具结果、上下文块与更早摘要的计数,`preserved` 写明系统提示词以及之后每一轮仍逐字保留的内容;这两部分始终绘出,其下的摘要则像其他上下文块一样折叠到 `contextPreviewLines` 行。检查点消息本身不再重复绘制。日志以错误结束的 `/compact` 尝试会在会话重绘时打印 `/compact failed · <error>`,因为实时运行的命令会自己报告失败;失败的自动尝试不改变任何内容,也不绘制任何内容,与浏览器一致。承载的行数多于其绘制行数的工具卡片与上下文块,结尾都是同一条标记:该块被对话记录的焦点持有时为 `… <n> more rows · Space expands`,否则为 `… <n> more rows · Ctrl+O expands`。回复中的围栏代码、`read` 卡片的文件行、`edit` 或 `write` diff 卡片的变更行——其中 `+` 新增项标为绿色、`-` 删除项标为红色,符号后的源文本按文件扩展名对应的语言绘制——以及 `!` / `!!` 草稿、用户 shell 的 `$ command` 行(其 `$` 用强调色)与终端工具卡片中的 shell 命令,都使用语法高亮,配色主题由终端自身的背景在明暗之间选定;某种语言的语法会在第一个用到它的代码块出现时才加载,因此该块先以纯文本绘制、随后被重绘为彩色;这里没有对应语法的语言、既不支持 24 位也不支持 256 色的终端,以及 `codeHighlight: false`,都会把每个代码块画成纯文本。标题与列表标记使用暖橙色,链接与行内代码使用紫色,引用保持暗色。流式推理、回复文字与工具参数到达时先入队,再按帧(默认约每秒 60 帧)分批绘制,因此一次网络突发会分摊到 `streamPaceFrames` 帧里,而不是一次落下,队列也从不拖慢模型调用。流式回复文字会淡入,而且每个词各走各的时钟:一个词以接近终端背景色的亮度出现,并经 `streamFadeSteps` 次、每次 `streamFadeStepMs` 提亮到它最终稳定的颜色,因此流得更快只会留下更长的一串正在提亮的词,而不会更暗。流式推理在同一时长内浮出:以抬高的颜色出现,再退回到稳定时的暗色斜体。工具卡片的每一列则在这段时长内从终端背景色亮起到它稳定时的调色板颜色;从持久化历史重绘的卡片不带流出或淡入,已经稳定下来的文字也不会再被调暗。
43
+ 每一帧都从终端左右两边各内缩一列绘制,因此对话记录与停靠的界面组件都不会有任何一行贴到两侧边缘。页眉在标题生成或设置后以标题命名会话,并在旁边显示 id。对话记录在终端自身的回滚区中增长:你的提示以 `❯` 开头,启用颜色时铺在一条通栏的着色背景带上(附件列在其下),而在已有模型步骤的轮次中被引导或注入的提示以暗色文字铺在更深的背景带上,退到它所加入的轮次之后,assistant 的推理以暗色斜体显示在 `✻ Thinking` 标题之下、Markdown 回复上方,流式期间标题旁的绽放符号随之旋转,每次工具调用是一张卡片,含状态符号(运行中为按工具族混合花朵、绽放与星形的黄色旋转指示、完成为绿色 `◆`、失败为红色 `◆`)、粗体青色工具名、以蓝绿色显示的呈现器标题(去掉呈现器重复写出的工具名,因此 `Read src/app.ts` 画成 `read src/app.ts`;shell 卡片取该次调用自身的摘要,绝不取命令,命令只由卡片的 `$` 行绘制一次)、运行中的一行加载标记,以及折叠到 `toolPreviewLines` 行的正文。顶层 workflow 调用还会在该卡片旁另绘一次运行:运行名、成员数、状态,以及一条十格的成员进度条与已结束数,然后是每个阶段和已启动的成员。实时运行进行中时,其 `◇` 以菱形动画脉动,每个运行中成员的 `○` 以子 agent 族的花朵旋转,相位比前一个成员领先一格;从重放日志绘制的运行只在其后台作业仍存活时旋转,减少动效时绘制静态符号。运行中的层级,以及含失败、取消或中断成员的层级会展开;干净完成的层级保持折叠。在运行或阶段上按 Space 或 Enter 折叠该层,在仍在运行的成员上按 Enter 只会在该子会话是本会话的直接子会话且仍在本进程运行时打开它。卡片在模型开始调用时出现,并逐行向外流出,每行从左到右,无论卡片装着什么,速度都一致:一整行宽的内容需 `toolRevealFrames` 帧,较短的行按比例更短,刚画出的列会从终端背景色亮起到各自的颜色。工具回答后,结果行也以同样方式流出,排在卡片尚未画完的内容之后;调用与结果都不会等待动画。`edit` 或 `write` diff 卡片把每一新增行整行铺满绿色背景、每一删除行整行铺满红色背景,删除的旧行在上、新增的新行在下,并把 `+` 与 `-` 画成各自更亮的颜色,使符号从填充色中读得出来;折行续行只延续填充色,不再画第二个符号;工具应用变更后,已应用的 hunk 取代调用时携带的 diff,并在每行前标出文件行号,新增行与未变行用新文件的行号,删除行用旧文件的行号。`subagent` 与 `subagent_*` 卡片折叠时只画一行,行首是同样的状态符号,运行中旋转,交给后台的子 agent 则为暗色 `◆`:运行中显示工具名、任务描述,以及调用指定的模型与 `background`;结束后描述变暗,右端标出 `[done]`,交给后台的子 agent 标 `[started]`,失败标 `[failed]`。在被标记的行上按 `Space`,或按 `Ctrl+O`,即可展开完整卡片。非空的系统提示词与每一条注入的上下文——instructions、catalogs、snapshots、notices、relays 与 recalls——绘制为暗色 `⬡` 标题,其下是面向模型文本的前 `contextPreviewLines` 行,快照的每一份贡献具名写在其自身各行上方;空的系统提示词则省略。一次压缩(compaction)——无论来自 `/compact` 还是自动触发——绘制为一个上下文块,其强调色 `⬡` 标题写明来源,以及被替换内容与摘要各自的估算 token 数,如 `context compacted by /compact · ~6.4k → ~0.9k tokens` 或 `context compacted automatically in turn 12 · …`;标题之下,`compressed` 写明摘要替换的条目数与轮次、其中的每条提示(最多五条,每条一行),以及回复、按工具分列的工具结果、上下文块与更早摘要的计数,`preserved` 写明系统提示词以及之后每一轮仍逐字保留的内容;这两部分始终绘出,其下的摘要则像其他上下文块一样折叠到 `contextPreviewLines` 行。检查点消息本身不再重复绘制。日志以错误结束的 `/compact` 尝试会在会话重绘时打印 `/compact failed · <error>`,因为实时运行的命令会自己报告失败;失败的自动尝试不改变任何内容,也不绘制任何内容,与浏览器一致。承载的行数多于其绘制行数的工具卡片与上下文块,结尾都是同一条标记:该块被对话记录的焦点持有时为 `… <n> more rows · Space expands`,否则为 `… <n> more rows · Ctrl+O expands`。回复中的围栏代码、`read` 卡片的文件行、`edit` 或 `write` diff 卡片的变更行——其中 `+` 新增项标为绿色、`-` 删除项标为红色,符号后的源文本按文件扩展名对应的语言绘制——以及 `!` / `!!` 草稿、用户 shell 的 `$ command` 行(其 `$` 用强调色)与终端工具卡片中的 shell 命令,都使用语法高亮,配色主题由终端自身的背景在明暗之间选定;某种语言的语法会在第一个用到它的代码块出现时才加载,因此该块先以纯文本绘制、随后被重绘为彩色;这里没有对应语法的语言、既不支持 24 位也不支持 256 色的终端,以及 `codeHighlight: false`,都会把每个代码块画成纯文本。标题与列表标记使用橙色,链接与行内代码使用品红色,引用保持暗色。每种色相都是 Tokyo Night(Night)配色,当 `COLORTERM` 声明 `truecolor` 或 `24bit` 时按原色精确绘制,否则取 256 色索引中最接近的一色;背景带保留其 256 色灰阶与 diff 底色。流式推理、回复文字与工具参数到达时先入队,再按帧(默认约每秒 60 帧)分批绘制,因此一次网络突发会分摊到 `streamPaceFrames` 帧里,而不是一次落下,队列也从不拖慢模型调用。流式回复文字会淡入,而且每个词各走各的时钟:一个词以接近终端背景色的亮度出现,并经 `streamFadeSteps` 次、每次 `streamFadeStepMs` 提亮到它最终稳定的颜色,因此流得更快只会留下更长的一串正在提亮的词,而不会更暗。流式推理在同一时长内浮出:以抬高的颜色出现,再退回到稳定时的暗色斜体。工具卡片的每一列则在这段时长内从终端背景色亮起到它稳定时的调色板颜色;从持久化历史重绘的卡片不带流出或淡入,已经稳定下来的文字也不会再被调暗。
44
44
 
45
- 对话记录下方依次是 agent 工作时的旋转指示——`thinking`、`writing`、`calling <tool>`、重试或 `compacting`,各自旁边是它自己的盲文动画:环绕的点、逐行填满的线、绕行的单点、滑动的横条,或沉降又回满的方格——标签单词上带着一道扫过的高亮,并带着当前这次模型调用的实时 `↑` 发送与 `↓` 接收 token,以紧凑的 `k` / `M` / `B` 计数,随数据流入增长,并在提供方的 usage 块到达后落定——任何打开的提示、有消息等待时的带框 follow-ups 列表、本轮 todo 与最新后代行的 activity board(有行时才绘制;已完成内容划掉,状态符号以绿色、黄色或青色显示,进行中的那一项为旋转指示,todo 最多四行其后 `+<n> more`,不是焦点区域,在 `turn/end` 与 bind 时消失)、编辑器、子 agent 面板,以及页脚:未聚焦时是一行由两端向内构建的状态栏。编辑器的光标是终端自身的闪烁竖条:应用在启动时请求这一形状,退出时把你的默认形状还回去,而状态栏或面板持有键盘期间完全不绘制光标。模型与入口按键带有颜色;进行中的轮次、上下文与 todo 信息分别使用黄色、紫色与绿色。模型锚定在左端且永不丢弃——超过 20 列时退回到裸模型名,只有仍然过宽的标签才会被省略号截断——离开编辑器的那两个按键则锚定在右端,写作 `Shift+↑ read · Shift+↓ status`,有 follow-ups 等待时则写作 `Shift+↑ select · Shift+↓ status`,窄到一定程度收缩为 `Shift+↑↓ nav`,不足 40 列时整体丢弃。关键事实填满剩下的中间部分,按状态栏顺序排列:推理强度(选择把推理交给模型时标为 `effort default`)、进行中轮次的已用时间、上下文窗口百分比、todo 计数,以及 workspace 路径(过长时以 `~` 与 `…/` 缩短)。中间部分容纳不下的每个分段都折进末尾的 `+N`,未聚焦行从不绘制的那些分段也一并折入——权限预设、token 用量(会话合计加上进行中的这次调用)、来自投影接缝的目标与计划模式标记,以及待发送附件的数量。模型请求重试以通知形式出现,与浏览器标记承载的事实相同。
45
+ 对话记录下方依次是 agent 工作时的旋转指示——`thinking`、`writing`、`calling <tool>`、重试或 `compacting`,各自旁边是它自己的盲文动画:环绕的点、逐行填满的线、绕行的单点、滑动的横条,或沉降又回满的方格——标签单词上带着一道扫过的高亮,并带着当前这次模型调用的实时 `↑` 发送与 `↓` 接收 token,以紧凑的 `k` / `M` / `B` 计数,随数据流入增长,并在提供方的 usage 块到达后落定——任何打开的提示、有消息等待时的带框 follow-ups 列表、本轮 todo 与最新后代行的 activity board(有行时才绘制;已完成内容划掉,状态符号以绿色、黄色或蓝色显示,进行中的那一项为旋转指示,todo 最多四行其后 `+<n> more`,不是焦点区域,在 `turn/end` 与 bind 时消失)、编辑器、子 agent 面板,以及页脚:未聚焦时是一行由两端向内构建的状态栏。编辑器的光标是终端自身的闪烁竖条:应用在启动时请求这一形状,退出时把你的默认形状还回去,而状态栏或面板持有键盘期间完全不绘制光标。模型为紫色,入口按键为品红色;进行中的轮次、上下文与 todo 信息分别使用黄色、品红色与绿色。模型锚定在左端且永不丢弃——超过 20 列时退回到裸模型名,只有仍然过宽的标签才会被省略号截断——离开编辑器的那两个按键则锚定在右端,写作 `Shift+↑ read · Shift+↓ status`,有 follow-ups 等待时则写作 `Shift+↑ select · Shift+↓ status`,窄到一定程度收缩为 `Shift+↑↓ nav`,不足 40 列时整体丢弃。关键事实填满剩下的中间部分,按状态栏顺序排列:推理强度(选择把推理交给模型时标为 `effort default`)、进行中轮次的已用时间、上下文窗口百分比、todo 计数,以及 workspace 路径(过长时以 `~` 与 `…/` 缩短)。中间部分容纳不下的每个分段都折进末尾的 `+N`,未聚焦行从不绘制的那些分段也一并折入——权限预设、token 用量(会话合计加上进行中的这次调用)、来自投影接缝的目标与计划模式标记,以及待发送附件的数量。模型请求重试以通知形式出现,与浏览器标记承载的事实相同。
46
46
 
47
47
  键盘在对话记录中移动时,编辑器正上方停靠着一个带边框的检视面板,边框即模式:它恰好在对话记录持有键盘时绘制。其顶边线带有一个反白的 ` ● READ ` 徽标与当前聚焦小节的标题——该小节在可导航块中的位置、所属轮次,以及这是哪一种小节——例如 `╭ ● READ ─ 3/12 · turn 2 · bash git status · result ─╮`。其下在块含多个部分时,把这些部分绘制成形如 `← 1 call · [2 result] →` 的带编号、会折行的选择行,被持有的标签除强调色外还加上方括号,因此完全无颜色时选择仍然可读;再往下是该小节自身的源文本行,每行左右两侧都由 `│ ` 边框闭合并按窄四列换行,对每一种小节——含系统提示词与注入的上下文——都折叠到 `focusPreviewLines` 行,其下写出 `… <n> more rows · Ctrl+G reads it`。底边线列出对话记录所应答的按键 `↑↓ sections · ←→ parts · Space folds · Ctrl+G reader · Esc input`,随着终端列数减少收缩为 `↑↓ ←→ · Space folds · Esc input`,再收缩为 `Esc input`。
48
48
 
49
49
  被聚焦的块也会在原地被标记:一条两列宽的标记条,在块的其他行旁为暗色、在被聚焦小节自身的行旁为强调色——若折叠把该小节整个留在了绘出的行之外,强调色便落在那一行折叠标记旁——标记绘制期间该块的内容按窄两列换行。这个标记只能落在 pi-tui 仍以差分方式重绘的行上——也就是它写出的上一帧的最后 `rows` 行,这条边界只会被更高的帧抬高、不会被更矮的帧降低——因为改动其上方的任何一行都会清空终端的回滚区。已经滚过该位置的块不带标记条,检视面板的标题追加 ` · off screen`,其边框线也改画暗色而非强调色,于是边框本身就报告出标记无法画在该块所在之处。淡入中的各行抵达这一边界时,会在写出它们的同一帧内被结算为最终颜色,因此回滚区里不会留下暗色文字。
50
50
 
51
- 在任一区域按 `Ctrl+G`、在对话记录的某个小节上按 `Enter`,以及 `/turns`,都会整屏读出对话记录,一次读一个轮次。阅读器并不画在对话记录之上,而是接管终端:它运行在终端的备用屏幕(alternate screen,分页器所用的那块屏幕)上,只要它还开着,对话记录自己的屏幕就被挡在终端之外。因此它不占用对话记录的任何一行,让重绘边界保持原位,在任何终端上都铺满整屏,也不可能把自己的任何一行留在你的回滚缓冲里;关闭它会把对话记录原样恢复成你离开时的样子,期间落地的内容则绘制在其下方。轮次面板滚过首行后,紧凑的着色条会替代顶边线,将当前用户提示合并为一行,并按终端宽度以省略号截断;滚回顶部时恢复 ` ● READER ` 徽标与 `turn <n> of <total>`。在这个固定页眉之下,正在阅读的轮次占据屏幕的大部分,左侧是一列窄的轮次列表,每个正文行都以右边框收口。列表每个轮次一行——正在阅读的轮次带 `❯`、轮次编号、其提示的首行,以及右对齐的标记 `⬡<n>` 注入上下文块数、`✻` 有推理、`¶` 有回复、`◆<n>` 工具调用数——并在正在阅读的那个轮次之下列出它的各小节,`▸` 落在阅读器所持的那一个上,因此任何轮次自己的上下文都只有一步之遥。轮次面板用对话记录自己的符号把该轮次从头到尾滚动读出,相邻两个小节之间隔一空行:提示以 `❯` 开头、铺在着色背景带上,其后是暗色斜体的 `✻ Thinking`、按对话记录的方式渲染 Markdown(标题、强调、行内代码,以及带语法着色的围栏代码)但无序列表符号画成 `•` 的 `¶ Reply`、工具调用的 `◆`(结果落地后为绿色、运行中为黄色)连同粗体工具名与链接蓝色的标题、缩进在调用之下的 `⎿ Result`(diff 的 `+ ` 行为绿色、`- ` 行为红色,各铺在着色背景带上;`read` 卡片的文件行带语法着色),以及带注入上下文标签的 `⬡`。顶行所属的小节带强调色,并在每一行带上对话记录走查所用的 `┃` 标记条,无色时也能辨认。背景带由终端报告的背景色混合而成,因此没有报告背景色、或不绘制颜色的终端画出的面板不带背景带。那里的行从不折叠:阅读器正是读取系统提示词、注入快照、长回复或工具结果完整面向模型文本的地方。`Right` 打开被选中的轮次,`Left` 回到轮次列表;在列表中 `Up` / `Down` 每次步进一个小节并跨入相邻的轮次,而 `PageUp` / `PageDown` 步进整个轮次;在轮次面板中它们逐行滚动,而顶行所属的小节就是阅读器关闭后对话记录恢复到的位置。`/` 在按键提示的位置打开一行查询,把轮次列表收窄到提示或文本匹配的轮次,读数写作 `<kept>/<total> turns`;其余时候提示边线在右端报告 `turn 3/12 · row 14/212`,任何宽度都不会丢弃它。列数不足 `readerMinColumns` 时正文一次只画一个面板——轮次列表,或由 `Right` 从中打开的那个轮次——不足 24 列或 8 行时只画一行暗色文字 `terminal too small for the reader (needs 24×8)`,并且只应答 `Esc`、`Ctrl+G` 与 `Ctrl+C`。它每一帧都会重新读取对话记录,只绘制视区内的小节,并在内容、宽度和样式与缓存匹配时复用已有行,因此长轮次在会话运行期间仍能保持响应;流式回复会在其中增长、落地的工具结果会出现、新轮次会加入轮次列表;重新换行时它按正在阅读的小节重新锚定,而不是按行号;审批或提问出现时它在该提示存续期间让位;切换会话会让它随通知 `the transcript changed · reader closed` 一同关闭。
51
+ 在任一区域按 `Ctrl+G`、在对话记录的某个小节上按 `Enter`,以及 `/turns`,都会整屏读出对话记录,一次读一个轮次。阅读器并不画在对话记录之上,而是接管终端:它运行在终端的备用屏幕(alternate screen,分页器所用的那块屏幕)上,只要它还开着,对话记录自己的屏幕就被挡在终端之外。因此它不占用对话记录的任何一行,让重绘边界保持原位,在任何终端上都铺满整屏,也不可能把自己的任何一行留在你的回滚缓冲里;关闭它会把对话记录原样恢复成你离开时的样子,期间落地的内容则绘制在其下方。轮次面板滚过首行后,紧凑的着色条会替代顶边线,将当前用户提示合并为一行,并按终端宽度以省略号截断;滚回顶部时恢复 ` ● READER ` 徽标与 `turn <n> of <total>`。在这个固定页眉之下,正在阅读的轮次占据屏幕的大部分,左侧是一列窄的轮次列表,每个正文行都以右边框收口。列表每个轮次一行——正在阅读的轮次带 `❯`、轮次编号、其提示的首行,以及右对齐的标记 `⬡<n>` 注入上下文块数、`✻` 有推理、`¶` 有回复、`◆<n>` 工具调用数——并在正在阅读的那个轮次之下列出它的各小节,`▸` 落在阅读器所持的那一个上,因此任何轮次自己的上下文都只有一步之遥。轮次面板用对话记录自己的符号把该轮次从头到尾滚动读出,相邻两个小节之间隔一空行:提示以 `❯` 开头、铺在着色背景带上,其后是暗色斜体的 `✻ Thinking`、按对话记录的方式渲染 Markdown(标题、强调、行内代码,以及带语法着色的围栏代码)但无序列表符号画成 `•` 的 `¶ Reply`、工具调用的 `◆`(结果落地后为绿色、运行中为黄色)连同粗体青色工具名与蓝绿色的标题、缩进在调用之下的 `⎿ Result`(diff 的 `+ ` 行为绿色、`- ` 行为红色,各铺在着色背景带上;`read` 卡片的文件行带语法着色),以及带注入上下文标签的 `⬡`。顶行所属的小节带强调色,并在每一行带上对话记录走查所用的 `┃` 标记条,无色时也能辨认。背景带由终端报告的背景色混合而成,因此没有报告背景色、或不绘制颜色的终端画出的面板不带背景带。那里的行从不折叠:阅读器正是读取系统提示词、注入快照、长回复或工具结果完整面向模型文本的地方。`Right` 打开被选中的轮次,`Left` 回到轮次列表;在列表中 `Up` / `Down` 每次步进一个小节并跨入相邻的轮次,而 `PageUp` / `PageDown` 步进整个轮次;在轮次面板中它们逐行滚动,而顶行所属的小节就是阅读器关闭后对话记录恢复到的位置。`/` 在按键提示的位置打开一行查询,把轮次列表收窄到提示或文本匹配的轮次,读数写作 `<kept>/<total> turns`;其余时候提示边线在右端报告 `turn 3/12 · row 14/212`,任何宽度都不会丢弃它。列数不足 `readerMinColumns` 时正文一次只画一个面板——轮次列表,或由 `Right` 从中打开的那个轮次——不足 24 列或 8 行时只画一行暗色文字 `terminal too small for the reader (needs 24×8)`,并且只应答 `Esc`、`Ctrl+G` 与 `Ctrl+C`。它每一帧都会重新读取对话记录,只绘制视区内的小节,并在内容、宽度和样式与缓存匹配时复用已有行,因此长轮次在会话运行期间仍能保持响应;流式回复会在其中增长、落地的工具结果会出现、新轮次会加入轮次列表;重新换行时它按正在阅读的小节重新锚定,而不是按行号;审批或提问出现时它在该提示存续期间让位;切换会话会让它随通知 `the transcript changed · reader closed` 一同关闭。
52
52
 
53
- 临时按键反馈以一行暗色带框文字浮在视口右上角:`press Esc again to stop turn <n>`、`press Ctrl+C again to quit` 与 `nothing in the transcript to read yet`。它以全亮度保持 `toastMs`、随后淡出,不占用对话记录自身的任何一行,也不接管键盘;渲染器已无法重绘视口顶部时,它改为打印进对话记录,从而被保留下来。值得留存的事实则是对话记录中的通知:`stopping the turn…`、`wait for the session switch to finish`、`above the repaint window · opened in the reader` 以及每一条命令结果。
53
+ 临时按键反馈以一行暗色带框文字浮在视口右上角:`press Esc again to stop turn <n>`、`press Ctrl+C again to quit`——有命令、后台作业或子 agent 在运行时为 `press Ctrl+C again to quit · stops 1 command, 2 background jobs`——与 `nothing in the transcript to read yet`。它以全亮度保持 `toastMs`、随后淡出,不占用对话记录自身的任何一行,也不接管键盘;渲染器已无法重绘视口顶部时,它改为打印进对话记录,从而被保留下来。值得留存的事实则是对话记录中的通知:`stopping the turn…`、`wait for the session switch to finish`、`above the repaint window · opened in the reader` 以及每一条命令结果。
54
54
 
55
55
  动效不止于流式文本:每种抬亮与浮出都乘着同一个淡入时钟,每种工作动画则乘着同一个旋转时钟。键盘落到对话记录、子 agent 面板或状态栏上时,会把该表层的边框、其徽标与它持有的标记抬亮十二拍(每拍一个 `streamFadeStepMs`);对话记录走查中的一步把新聚焦的标记条抬亮六拍;状态栏上的一步把所选标签抬亮八拍。活动板上新出现或状态已变的 todo 行,以及被替换的后代行,也在淡入时钟上浮出;重放与 `reducedMotion` 则画出已稳定的活动板。每种工作动画都有八帧,由时钟决定当前画哪一帧,并在周期为 `spinnerMs`(默认 100 ms)的旋转时钟上步进,因此一切旋转中的指示都在同一时刻、以同一速度前进,标签变化也不打乱节拍,而该时钟只在其中之一被绘制时才启动。只有工作时的旋转指示画盲文,其动画随状态而变,因此它从不与卡片的符号重复。运行中的工具卡片与折叠的子 agent 行画该工具族的动画,进行中的 todo 行画规划族的动画。这些动画都把花朵、绽放与星形混在同一组帧里,族与族之间不共用符号,同一族的每一帧也各不相同,因此同一族里相位不同的两个指示在任何时刻都不会画出相同的符号。某个指示开始旋转时若同族已有其他指示在转,它会取一个相位,使它在任何时刻都不与它们画出相同的符号,同族同时旋转的不超过八个时都能做到;超过八个后,它取同族中被持有指示最少的那个相位。标题行已滚动到渲染器可重绘区域之上的卡片自此画出静态的 `◆`,而 `reducedMotion` 把它们全部画成静止的——卡片的 `◆`、todo 的 `▸`,以及不带符号、只剩标签的工作旋转指示——且不启动旋转时钟。阅读器在自己占据的屏幕上一次性完整出现,而它新显示的内容会在淡入时钟上浮出:打开它与显示另一个轮次时浮出整个轮次,在列表中步进到同一轮次的另一个小节时浮出该小节,历时 `streamFadeSteps` 拍;滚动、实时增长与重新换行都不浮出任何内容。任何抬亮都不改变任何东西绘制的行数,而 `reducedMotion`——与 `NO_COLOR`、被禁用的调色板和 `TERM=dumb` 一样——会关闭每一种抬亮与浮出,并且不为它们安排任何重绘。
56
56
 
@@ -86,7 +86,7 @@ dsh tui --no-open # print sign-in URLs without opening a
86
86
  | `Ctrl+L` | 从头重绘整个屏幕 |
87
87
  | `?` | 输入为空时列出命令与按键,与 `/help` 相同;在草稿中则作为文字输入 |
88
88
  | `Esc` | 取消正在运行的 `!` 或 `/compact`;在没有轮次进行且草稿以 `!` 开头时清空编辑器;否则装填停止,该提示仍在屏幕上时再按一次会停止正在进行的轮次 |
89
- | `Ctrl+C` | 清空编辑器;600 ms 内再按一次则退出 |
89
+ | `Ctrl+C` | 清空编辑器并装填退出;`press Ctrl+C again to quit` 这一行仍在屏幕上时再按一次即退出 |
90
90
  | `Ctrl+D` | 编辑器为空时退出 |
91
91
 
92
92
  仅仅交还了键盘的 `Esc`——离开某个区域、关闭页面、选择器或阅读器——会打开一个 750 ms 的窗口,其间到达编辑器的 `Esc` 完全不做任何事,因此习惯性的连按停不掉任何轮次。没有轮次进行时,`Esc` 在补全列表打开时关闭它,清空以 `!` 开头的草稿,其余情况保持沉默。尚无可读内容的会话对 `Shift+Up`(没有 follow-up 等待时)与 `Ctrl+G` 回以 `nothing in the transcript to read yet`,并把键盘留在编辑器。
@@ -190,7 +190,7 @@ follow-ups 面板持有键盘时:
190
190
  | `/login` | 用提供方订阅登录(隐藏仅收集密钥的登录);`/login <key>` 跳过选择器 |
191
191
  | `/export [dir]` | 把本会话的日志 ZIP(含子会话与附件)写入 `dir`,默认 workspace |
192
192
  | `/status` | 上下文窗口用量与构成、含缓存命中的 token 总计、会话统计、todo、目标、计划模式与权限 |
193
- | `/context` | 上下文窗口此刻的用法:200 个单元格的网格,旁边是模型、占用,以及系统提示词、工具定义、指令文件、技能、其他注入上下文与消息的估算 token,最后是剩余空间。保存最新一轮新增 token 的单元格是热区,以粗体绘制,并在 `▲ hot` 行计数。终端运行动效时,网格在打开时逐格填充,一道亮带扫过热区;轮次进行期间,报告每四分之一秒重新读取用量、标记为 `live`,并让第一个空闲单元格闪烁。当没有轮次进行且打开动画结束、另一个 `/context` 打开、会话切换,或它离开重绘窗口时,报告定格。减弱动效时只绘制定格后的报告 |
193
+ | `/context` | 上下文窗口此刻的用法:200 个单元格的网格,旁边是模型、占用,以及系统提示词、工具定义、指令文件、技能、其他注入上下文与消息的估算 token,最后是剩余空间。每个类别以自己的色相绘制单元格——系统提示词蓝色、工具青色、指令橙色、技能黄色、其他上下文绿色、消息品红色。保存最新一轮新增 token 的单元格是热区,以粗体绘制,并在 `▲ hot` 行计数。终端运行动效时,网格在打开时逐格填充,一道亮带扫过热区;轮次进行期间,报告每四分之一秒重新读取用量、标记为 `live`,并让第一个空闲单元格闪烁。当没有轮次进行且打开动画结束、另一个 `/context` 打开、会话切换,或它离开重绘窗口时,报告定格。减弱动效时只绘制定格后的报告 |
194
194
  | `/todos` | 浏览 agent 的 todo 列表;已完成行会被划掉;`Enter` 完整打开其中一条,含其状态、位置与轮次 |
195
195
  | `/outline` | 本会话各轮次及其提示与回复预览 |
196
196
  | `/deliverables` | agent 交付的文件,按轮次分组 |
@@ -228,6 +228,18 @@ follow-ups 面板持有键盘时:
228
228
 
229
229
  `@` 后接文本会列出匹配的文件与目录——相对工作区、从工作区出发的 `../`、从家目录出发的 `~/`、或绝对路径——以及其他会话,使用与浏览器编辑器插入相同的提及语法(`@path`、`@"path with spaces"` 与不透明的 `@[label](…)` 会话标记);base 行把这些提及解析进提示,与浏览器中完全一致。`/attach <path>` 读取相对于 workspace 的本地文件并通过已组合的附件存储保存:`.png`、`.jpg`、`.jpeg`、`.webp` 与 `.gif` 作为图片块,其余作为文件块;待发送附件随下一条提示一起发送,并列在其下。
230
230
 
231
+ <a id="quitting"></a>
232
+ ### 退出
233
+
234
+ 按两次 `Ctrl+C`、在空输入上按 `Ctrl+D`、`/quit` 与 `/exit` 都会退出;第二次 `Ctrl+C` 必须在 `press Ctrl+C again to quit` 仍在屏幕上时到达,其间按下的任何其他键都会解除第一次的装填。退出会清点根会话之下正在运行的命令、后台作业与子 agent,停止正在运行的 `!` 命令,并把终端交还给你的 shell。随后它按顺序停止其余工作:取消进行中的轮次(这会停止模型的命令),等待 agent 进入空闲,保存会话日志,并释放会话(这会停止其后台作业与子 agent)。某一步失败不会跳过其后的步骤。在此期间应用向 stderr 写入:
235
+
236
+ - 有工作在运行时写 `dsh: stopping <work> (Ctrl+C to force)`,其中 `<work>` 形如 `1 command, 2 background jobs, 1 subagent`;之后每 2 s 写一次 `dsh: still stopping <work> (Ctrl+C to force)`,写明仍在运行的工作。
237
+ - 停止过程超过 `quitGraceMs` 时写 `dsh: gave up waiting after <N>s; <work> may still be running`,`Ctrl+C` 结束等待时写 `dsh: forcing exit; <work> may still be running`;已没有工作在运行时,这两行都省略 `; <work> may still be running`。
238
+ - 每个失败的步骤写 `dsh: saving the session failed: <reason>` 或 `dsh: stopping failed: <reason>`。
239
+ - 只要会话日志已保存,最后写 `dsh: session <id> saved; resume with: dsh --profile tui --resume <id>`。
240
+
241
+ `Ctrl+C` 结束等待时退出码为 130,终端关闭时为 129,等待放弃或某一步失败时为 1,其余情况为 0。`quitGraceMs`(默认 10000 ms,至少 1000)限定整个停止过程;超过之后,启动器自身的 dispose 最多再等 5 s,并在进程退出时杀掉仍在运行的命令进程。关闭终端会发送 `SIGHUP`,它运行同样的停止过程;写往已关闭终端的输出被丢弃。命令从自身进程树中脱离出去的进程可能在退出后继续存活;参见[已知限制与延期工作](#known-limitations-and-deferred-work)。
242
+
231
243
  ### 配置
232
244
 
233
245
  | 字段 | 默认值 | 含义 |
@@ -239,7 +251,8 @@ follow-ups 面板持有键盘时:
239
251
  | `focusPreviewLines` | `12` | 停靠的检视面板为聚焦小节显示的行数,其后由折叠标记把剩余部分交给阅读器;对每一种小节都适用 |
240
252
  | `readerMinColumns` | `60` | 阅读器把被选中的轮次画在轮次列表旁边所需的列数;不足时一次只画一个面板 |
241
253
  | `codeHighlight` | `true` | 以语法高亮绘制回复中的围栏代码、`read` 与 diff 工具卡片的文件行,以及 `!` / `!!` 草稿、`$ command` 行与终端工具卡片中的 shell 命令,配色主题由终端背景选定 |
242
- | `toastMs` | `2000` | 临时按键提示行以全亮度保持多久后淡出,这同时也是第二次 `Esc` 停止正在进行轮次的窗口 |
254
+ | `toastMs` | `2000` | 临时按键提示行以全亮度保持多久后淡出;该行仍在屏幕上时,第二次 `Esc` 停止正在进行的轮次,第二次 `Ctrl+C` 退出 |
255
+ | `quitGraceMs` | `10000` | 退出时等待进行中的轮次停止、会话日志保存、会话的后台作业与子 agent 停止的时长,超过后写明可能仍在运行的工作并以退出码 1 退出;随后是启动器自身 5 s 的 dispose。低于 1000 的值会被拒绝 |
243
256
  | `liveRefreshMs` | `1000` | 重绘周期:推进 `turn` 分段与面板中的已用时间,并重新读取已过期的子 agent 列表 |
244
257
  | `streamFadeSteps` | `24` | 一次淡入或浮出持续多少拍:回复文字与工具卡片的列淡入,推理浮出,时长为 `streamFadeSteps × streamFadeStepMs` |
245
258
  | `streamFadeStepMs` | `16` | 一帧的时长:淡入或浮出的一拍、仍在变化时的重绘周期,也是逐帧绘制流式文字的周期;总时长为 `streamFadeSteps × streamFadeStepMs` |
@@ -266,7 +279,7 @@ runner 与 `dsh-headless` 一样是核心 API 载体之上的直接驱动器,
266
279
 
267
280
  ### 运行流程
268
281
 
269
- runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心注册表之上构建含五个操作的会话宿主:`create` 用传入的选择或共享的 [`agentDefaultModel`](../../core/agent-default-model/README.zh.md) 选择创建一个全新的持久化 Agent,`resume` 先拿到 Agent 写句柄,再经 `ctx.sessionQuery` 观察实时 Session,使 bind 画出每条持久化事件(包括恢复时的闭合事件),`fork` 通过 `ctx.sessionQuery` 观察源会话、在所选(默认最后一个)`turn/end` 之后直到下一个 `turn/start` 处切割,并创建带 `parentSession` 与 `isSeeded` 元数据的种子 Agent,`observe` 打开子 agent 会话而不释放已绑定的会话——常驻的子 agent Agent 被实时读取、释放它什么也不做,其他会话则被恢复,`aside` 创建 `/btw` 旁路 agent:它以 `buildForkSeed` 用 `ctx.sessionQuery` 观察到的已绑定会话完整日志作种子,记录 `parentSession`、`isSeeded` 与 `origin: 'subagent'`,但不传入父 Agent,也不向父会话追加目录事件,随后在其 setup 中追加 `read-only` 沙箱模式与 `never` 审批策略,并把它的全局工具限制为配置的名称。除常驻会话的 `observe` 外,每个操作都在 Agent 的作用域 setup 中安装 `ModelSelectionRef`,因此 `/model` 会改变下一次请求;`resume` 把启动默认作为 AgentOptions 传入,使组装时 `{{model}}` 有值,再在有请求头时把它覆盖到该选择上,否则保留该默认。终端应用从 `--resume` 或一次新的 `create` 产生的会话开始,订阅 `session/event`、`agent/assistant-stream` 与 `agent/status`,为绑定的 Agent 以及每个被视图挡在后面的会话应答 `approval/request` 与 `user-questions/request` waterfall,并通过绑定下一个会话、dispose 先前句柄来切换会话;宿主打开下一个会话期间编辑器拒绝输入,等待期间退出会释放随后到达的会话。退出时取消任何进行中的轮次、等待完全停稳、flush 绑定的会话、dispose 其句柄并请求以 0 退出;驱动器失败会向 stderr 写入 `dsh: <message>` 并请求以 1 退出。`/resume` 与 `/sessions` 共用持久化会话选择器。编辑器中的 `Shift+Tab` 会派发空参数 `/effort` 以打开当前模型的推理强度选择器,而编辑器中的 `Shift+Left` / `Shift+Right` 使用 pi-tui 的词导航。`/login` 只带着订阅方法(除收集密钥的 `api-key` 登录外的每一种方法)启动 `authorization.begin`。flow 用 `openInBrowser` 标记的 notice 会经 `dsh-native-command` 的凭据擦除辅助进程交给默认浏览器,URL 同时保持打印;当 `openBrowser` 为 false、启动经过 SSH 或宿主没有桌面时抑制该交接,打开器失败则成为 URL 旁的一条通知,而非登录失败。编辑器里提交的非空 `!` 或 `!!` 行经本进程的 `ctx.shell` 运行;`!` 注入一条下一步通知,`!!` 只留在本地。
282
+ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心注册表之上构建含五个操作的会话宿主:`create` 用传入的选择或共享的 [`agentDefaultModel`](../../core/agent-default-model/README.zh.md) 选择创建一个全新的持久化 Agent,`resume` 先拿到 Agent 写句柄,再经 `ctx.sessionQuery` 观察实时 Session,使 bind 画出每条持久化事件(包括恢复时的闭合事件),`fork` 通过 `ctx.sessionQuery` 观察源会话、在所选(默认最后一个)`turn/end` 之后直到下一个 `turn/start` 处切割,并创建带 `parentSession` 与 `isSeeded` 元数据的种子 Agent,`observe` 打开子 agent 会话而不释放已绑定的会话——常驻的子 agent Agent 被实时读取、释放它什么也不做,其他会话则被恢复,`aside` 创建 `/btw` 旁路 agent:它以 `buildForkSeed` 用 `ctx.sessionQuery` 观察到的已绑定会话完整日志作种子,记录 `parentSession`、`isSeeded` 与 `origin: 'subagent'`,但不传入父 Agent,也不向父会话追加目录事件,随后在其 setup 中追加 `read-only` 沙箱模式与 `never` 审批策略,并把它的全局工具限制为配置的名称。除常驻会话的 `observe` 外,每个操作都在 Agent 的作用域 setup 中安装 `ModelSelectionRef`,因此 `/model` 会改变下一次请求;`resume` 把启动默认作为 AgentOptions 传入,使组装时 `{{model}}` 有值,再在有请求头时把它覆盖到该选择上,否则保留该默认。终端应用从 `--resume` 或一次新的 `create` 产生的会话开始,订阅 `session/event`、`agent/assistant-stream` 与 `agent/status`,为绑定的 Agent 以及每个被视图挡在后面的会话应答 `approval/request` 与 `user-questions/request` waterfall,并通过绑定下一个会话、dispose 先前句柄来切换会话;宿主打开下一个会话期间编辑器拒绝输入,等待期间退出会释放随后到达的会话。退出在根绑定上运行 `src/quit.ts` 中的序列:取消任何进行中的轮次、等待完全停稳、flush 根会话、dispose 其句柄,每一步都被隔离,失败不会跳过下一步;该序列与 `quitGraceMs` 以及只在退出期间注册的 `SIGINT` 监听器竞争,之后写出结果行,并请求报告映射出的退出码;runner 作为 effect 注册的 `SIGHUP` 监听器运行同样的退出,并把终端视为已消失。驱动器失败会向 stderr 写入 `dsh: <message>` 并请求以 1 退出。`/resume` 与 `/sessions` 共用持久化会话选择器。编辑器中的 `Shift+Tab` 会派发空参数 `/effort` 以打开当前模型的推理强度选择器,而编辑器中的 `Shift+Left` / `Shift+Right` 使用 pi-tui 的词导航。`/login` 只带着订阅方法(除收集密钥的 `api-key` 登录外的每一种方法)启动 `authorization.begin`。flow 用 `openInBrowser` 标记的 notice 会经 `dsh-native-command` 的凭据擦除辅助进程交给默认浏览器,URL 同时保持打印;当 `openBrowser` 为 false、启动经过 SSH 或宿主没有桌面时抑制该交接,打开器失败则成为 URL 旁的一条通知,而非登录失败。编辑器里提交的非空 `!` 或 `!!` 行经本进程的 `ctx.shell` 运行;`!` 注入一条下一步通知,`!!` 只留在本地。
270
283
 
271
284
  ### 渲染模型
272
285
 
@@ -280,11 +293,12 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
280
293
 
281
294
  | 文件 | 职责 |
282
295
  |---|---|
283
- | [`src/index.ts`](src/index.ts) | `tui-app` 插件:会话宿主(创建、恢复、fork、观察)、恢复观察、退出流程、退出码映射 |
296
+ | [`src/index.ts`](src/index.ts) | `tui-app` 插件:会话宿主(创建、恢复、fork、观察)、恢复观察,以及退出的接线:`SIGHUP` 与 `SIGINT` 监听器、时间预算、结果行与退出请求 |
297
+ | [`src/quit.ts`](src/quit.ts) | 退出序列:运行中工作的清点及其措辞、有序、隔离且有界的停止,以及一份报告映射出的 stderr 行与退出码 |
284
298
  | [`src/resume-model.ts`](src/resume-model.ts) | 恢复时的模型选择:来自最后一条请求头,否则为启动默认 |
285
299
  | [`tests/resume-model.spec.ts`](tests/resume-model.spec.ts) | 恢复沿用上次记录的路由,没有请求头时则用启动默认 |
286
300
  | [`src/startup.ts`](src/startup.ts) | `tui-app-startup` 提供方:提示位置参数、`--resume`、`--no-open` 与 `--help` |
287
- | [`src/app.ts`](src/app.ts) | 终端应用:布局、按键路由、命令、会话绑定、接缝、日志与流的折叠、编辑器上方的 activity board、停止装填、它挂载的临时提示行、阅读器所依托的终端交接,以及提交时解析的 `!` / `!!` |
301
+ | [`src/app.ts`](src/app.ts) | 终端应用:布局、按键路由、命令、会话绑定、接缝、日志与流的折叠、编辑器上方的 activity board、停止与退出的装填、退出所停止工作的清点、它挂载的临时提示行、阅读器所依托的终端交接,以及提交时解析的 `!` / `!!` |
288
302
  | [`src/keys.ts`](src/keys.ts) | 按键模型:各焦点区域、一次按键在每个区域中的含义、它们逐级收缩的按键提示、进入用的按键、`/help` 的各行,以及交接窗口 |
289
303
  | [`src/sessions.ts`](src/sessions.ts) | `/resume` 与 `/sessions` 共用的持久化会话列表及选择器行;标题来自实时或缓存的 title 投影 |
290
304
  | [`src/effort.ts`](src/effort.ts) | `/model`、`/effort` 与编辑器 `Shift+Tab` 共用的推理强度名称及选择器行 |
@@ -315,7 +329,7 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
315
329
  | [`src/pinned-prompt.ts`](src/pinned-prompt.ts) | 阅读器在轮次面板滚动后固定在顶部的提示行:符号、合并为一行的提示,以及背景带 |
316
330
  | [`src/transcript.ts`](src/transcript.ts) | 呈现视图、用量与轮次结束原因的纯文本折叠、`$ command` 的 span,以及每条标记共用的那一套折叠措辞 |
317
331
  | [`src/diff.ts`](src/diff.ts) | diff 卡片的行 diff、hunk 选择,以及卡片加框所依据的新增与删除标记 |
318
- | [`src/style.ts`](src/style.ts) | 调色板(含 Markdown 回复所用的暗色冷色阶标题与链接色、已完成 todo 内容所用的划线角色、提示所铺的背景带与被引导或注入的提示所铺的更深背景带、diff 卡片变更行的绿色与红色填充及符号颜色)、按键徽标是否可点击,以及派生的 pi-tui 主题 |
332
+ | [`src/style.ts`](src/style.ts) | 调色板:以真彩色或 256 色 SGR 表示的 Tokyo Night 色相,以及用这些色相绘制的语义角色(含 Markdown 回复所用的标题与链接色、工具名、调用对象与模型的色相、已完成 todo 内容所用的划线角色、提示所铺的背景带与被引导或注入的提示所铺的更深背景带、diff 卡片变更行的绿色与红色填充及符号颜色)、按键徽标是否可点击,以及派生的 pi-tui 主题 |
319
333
  | [`src/highlight.ts`](src/highlight.ts) | 围栏代码、文件行与 shell 命令的语法高亮:某个块可能加载的语法、由背景选定的配色主题,以及一个 token 所用的 SGR |
320
334
  | [`src/completion.ts`](src/completion.ts) | 编辑器的斜杠命令与 `@` 引用补全 |
321
335
  | [`src/editor.ts`](src/editor.ts) | 提示编辑器的终端光标、把 `Shift+Left` / `Shift+Right` 映射到 pi-tui 词导航的逻辑,以及 `!` / `!!` 草稿上的语法高亮 |
@@ -332,7 +346,7 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
332
346
  | [`src/todos.ts`](src/todos.ts) | todo 列表:状态符号、已完成内容划掉的选择器行与单个条目的详情行 |
333
347
  | [`cordis.patch.yml`](cordis.patch.yml) | 基于 `dsh-base` 的终端 patch |
334
348
  | — | 不发布运行时不变量伴随模块;应用只在一个 Agent 上注册监听器,不持有其他观察者可能与之矛盾的可变关系。 |
335
- | [`tests/app.spec.ts`](tests/app.spec.ts) | 基于伪终端的渲染、按键、命令、停止装填、编辑器上方的 follow-ups 行、activity board 与两个接缝 |
349
+ | [`tests/app.spec.ts`](tests/app.spec.ts) | 基于伪终端的渲染、按键、命令、停止与退出的装填、编辑器上方的 follow-ups 行、activity board 与两个接缝 |
336
350
  | [`tests/background.spec.ts`](tests/background.spec.ts) | 基于真实工具运行时、作业注册表与作业工具的 `Ctrl+B`:旋转指示提示、被移走的结果与卡片、作业行、`/jobs` 输出与 `Ctrl+K`、完成通知、拒绝、失败与轮次停止 |
337
351
  | [`tests/background-tracking.spec.ts`](tests/background-tracking.spec.ts) | 包装器跟踪哪些调用、哪些作业算作调用自己的作业,以及被移走结果的文本 |
338
352
  | [`tests/jobs-panel.spec.ts`](tests/jobs-panel.spec.ts) | 作业行、`/jobs` 的行、详情页与作业结束提示行的文本 |
@@ -366,10 +380,12 @@ runner 等待完整应用就绪(`ctx.get('loader')?.await()`),并在核心
366
380
  | [`tests/compaction-app.spec.ts`](tests/compaction-app.spec.ts) | 终端中的 `/compact`:旋转指示、`Esc`、排队的提示、被拒绝的切换、取代结果的压缩块,以及从重放日志绘出的压缩块 |
367
381
  | [`tests/sessions.spec.ts`](tests/sessions.spec.ts) | 会话选择器列表:最新在前、实时或缓存标题、隐藏子 agent |
368
382
  | [`tests/index.spec.ts`](tests/index.spec.ts) | 创建、恢复分页、恢复时的模型组装、fork 切割、会话切换、退出流程与失败报告 |
383
+ | [`tests/quit.spec.ts`](tests/quit.spec.ts) | 退出顺序、时间预算、强制退出、被隔离的步骤失败、进度通知,以及每种结果映射出的输出行与退出码 |
369
384
  | [`tests/startup.spec.ts`](tests/startup.spec.ts) | 基于真实 Loader 配置树的命令行解析 |
370
385
  | [`tests/shortcuts.spec.ts`](tests/shortcuts.spec.ts) | 空输入与草稿中的 `?`、任一区域的 `Ctrl+T`、根会话上的 `Ctrl+P`,以及 `Ctrl+L` 重绘 |
371
386
  | [`tests/subagents.spec.ts`](tests/subagents.spec.ts) | 实时子 agent 面板的各行、走查与列表刷新,以及它与 `/subagents` 打开的子 agent 视图:经 `/parent` 与 `Ctrl+P` 离开,并在会话切换与退出时释放 |
372
387
  | [`../../../apps/cli/tests/profiles/tui/tests/keyless-smoke.e2e.ts`](../../../apps/cli/tests/profiles/tui/tests/keyless-smoke.e2e.ts) | 通过真实启动器与免密钥模拟模型运行随附 profile |
388
+ | [`../../../apps/cli/tests/profiles/tui/tests/quit-while-busy.e2e.ts`](../../../apps/cli/tests/profiles/tui/tests/quit-while-busy.e2e.ts) | 已发布的配置文件在命令、后台作业、子代理或忽略 `SIGTERM` 的进程仍在运行时退出,以及收到 `SIGHUP` 与 `SIGINT` 时的表现:stderr 输出行及其顺序、退出码,以及没有进程残留 |
373
389
 
374
390
  ### 不变量归属
375
391
 
@@ -479,6 +495,7 @@ The user moved this call to the background. It keeps running as job <id>. You ar
479
495
  - **点击需要终端配合**——设置 `mouse: true` 后,终端的鼠标报告在整个运行期间都处于打开状态,因此不按住 `Shift` 时,滚轮与普通的点击拖动不再滚动回滚缓冲区或选择文本;主屏幕上的点击依据终端对光标位置查询的应答来定位,因此从不应答的终端会忽略主屏幕上的点击,而阅读器的屏幕不需要应答;终端向回滚动时,回滚缓冲区中的徽标无法点击,因为鼠标报告指的是实时屏幕上的行。
480
496
  - **终端自身的光标可能闪烁**——编辑器不绘制自己的光标,应用打开终端光标,而 pi-tui 会在其重绘的各行之间移动它;不支持 pi-tui 为一帧包裹的同步输出序列的终端可能显示出这种移动。
481
497
  - **通过 `dsh` 启动器运行**——以其他方式启动该 profile 会在启动时失败,因为只有启动器能请求进程退出。
498
+ - **命令脱离出去的进程可能在退出后存活**——在 macOS 上,以及在没有可用 user-systemd scope 的 Linux 上,退出会停止每个运行中命令的进程组,以及进程树中仍在该命令之下的后代进程,但通过两次 fork 脱离它(被重新挂到 1 号进程下)的进程不被追踪,会继续运行;Linux 原生模式把这类进程保留在该命令的 scope 中。[subprocess-local 的限制](../../subprocess/subprocess-local/README.zh.md#known-limitations-and-deferred-work)说明各平台提供的隔离范围。
482
499
  - **`/btw` 旁路 agent 靠工具名称与沙箱保持只读**——`btwTools` 只能列出读取类工具,因为旁路 agent 与工作 agent 共享工作区;命令工具可以读取 `read-only` 沙箱模式允许的任何内容,而没有会约束命令的执行器时命令工具会被隐藏。它只继承工作会话已记录的内容:仍在流式输出的回复文本不在其中。它的日志像子 agent 会话一样被存储,并在 `/resume` 与 `/sessions` 中隐藏,Web 没有 `/btw`。
483
500
  - **被移走的调用仍绑定其轮次并返回文本**——工具运行时把轮次的信号融合进每个调用,因此即便按过 `Ctrl+B`,在派发该调用的轮次上按 `Esc` 仍会停止它;作业结果是字符串,因此调用结果中的其他内容块会被写成 `[image omitted]` 之类;移走调用需要 `ctx.jobs` 与 `dsh-tool-jobs`,base profile 已组合二者。
484
501
  - **工作流运行块只显示身份与状态**——顶层 workflow 调用在工具卡片旁另绘运行块:运行名、成员数、状态、进度、阶段和已启动的成员。`/workflows` 只停止后台运行;轮次内的运行随轮次一起停止。运行中与异常的层级默认展开,干净完成的层级保持折叠。在运行或阶段上按 Space 或 Enter 折叠该层。在仍在运行的成员上按 Enter 只会在它是本会话的直接子会话且仍在本进程运行时打开,不会恢复已结束的成员。脚本留在工具卡片上。后台运行在其作业仍存活时,启动轮次结束后仍显示为运行中;重放时没有存活作业的未结束运行显示为 interrupted。阶段与日志行留在 `/jobs`,作业返回值仍由 `job_output` 交给模型。