kward 0.72.0 → 0.73.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32f9966cff49fb90d0c11f20277e77186fe439ede174a3d151a2a3dfdcddc726
-  data.tar.gz: ebcdfd83477ce0e90857019a67f8bfdf57f2f2e9cb4e7accdd89b790d6002b5c
+  metadata.gz: cfccb9f2d7d186ac01b3d8d9029b1782072171acfcaeeecafa85d8d030ee3bbb
+  data.tar.gz: bd7f40e1913ad63bde53002b07b9172622b83e72f8884319e55495ab55c06a10
 SHA512:
-  metadata.gz: 9c625a36cf64cb7348f1ff14a07bd27e6b311bcd2d5b219669885d105118977143f17d1321d0acfefddc81469c0a11311868b8e8905d2d5a68339065dddf0513
-  data.tar.gz: 7de5e8b2887d654d57bd2032fa86b4fad7b3c0859d74d323e4d9f44cd682b7f7b616a11858e5e20bb4f2cc5a829d3746f94576fb114a35504581a45a66adbb16
+  metadata.gz: 13bda62de913cc4e3b97384fe6ca980e61bb6c4c6f6e640193e8dc3a34d27db6958dc6a46f365056636181290d0e7d333f65c86c207903890481ffad83e54952
+  data.tar.gz: e80fb5f0d668f619ed231c929e7c9a30d654ed4c8404035f04c114d0fe1567b480afc0bb7d3e149768db1c2b9ad241a94c7cbaf90b04ba10c59c01c45accfce0

data/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Check syntax
+        run: find lib test -name '*.rb' -print0 | xargs -0 ruby -c
+
+      - name: Run tests
+        run: bundle exec rake test

data/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to Kward will be documented in this file.
 
+## [Unreleased]
+
+## [0.73.1] - 2026-06-30
+
+### Fixed
+
+- Fixed session picker delete confirmation in terminals that send printable keys as CSI-u escape sequences.
+
+## [0.73.0] - 2026-06-29
+
+### Added
+
+- Added persistent session-backed worker queue job metadata as the first step toward tab-based worker queues.
+- Added experimental `/queue add` and `/queue list` commands for enqueueing the current tab session into the worker queue.
+- Added a first session-backed worker queue runner that executes one queued job and marks it ready for review after committing changes.
+- Added clean-workspace blocking for queued workers so jobs do not start on top of existing local changes.
+- Added `/queue run` to manually drain queued tab worker jobs sequentially until the queue is empty or a job needs attention.
+- Added worker git stash helpers as groundwork for cooperative queue suspension.
+- Added explicit queue runner suspend/resume primitives that stash and restore a running job's workspace changes.
+- Added `/queue suspend <id>` and `/queue resume <id>` commands for manually parking and resuming queued worker jobs.
+- Added `/queue open <id>` to open a queued worker's session for review or follow-up.
+- Added `/diff` to open the chronological file changes recorded in the current session in the integrated diff viewer.
+- Added `/scratchpad [text|markdown|ruby]` for opening unsaved editor buffers, including Vibe `:w filename` save-as support and Ruby `:run`/Modern `Ctrl+R` output written after `__END__`.
+- Added `/pty <command>` and the `ekwsh` `pty <command>` built-in for explicit interactive PTY passthrough sessions, enabling terminal-owned tools such as pagers to run from Kward.
+- Added minimal PTY execution for external `ekwsh` commands so terminal-aware tools can detect a TTY and terminal width.
+- Added Ctrl+C cancellation for running `ekwsh` commands and preserved tab-switch actions while shell commands are active.
+- Added quoted path completion and cached `$PATH` executable completion for `ekwsh`.
+- Added streaming `ekwsh` command output in the TUI transcript while commands run.
+- Added separate workspace-scoped `ekwsh` command history so embedded shell input no longer shares normal prompt history.
+- Added structured RPC `runtime/updateSetting` `defaultModel` values so clients can send provider and model separately while keeping the existing string format.
+
+### Changed
+
+- Changed PTY-backed `ekwsh` commands to refresh terminal window size while running so long-lived commands can adapt to resizes.
+- Changed `ekwsh` to default `GIT_PAGER` to `cat`, while preserving user-provided values, so Git commands do not unexpectedly enter an interactive pager under PTY execution.
+- Improved `ekwsh` POSIX-oriented built-ins, including `exit [status]`, stricter `cd`/`pwd`, `export NAME`, assignment persistence, `unalias`, and shared alias-name validation.
+- Changed `ekwsh` configuration to prefer a POSIX `/bin/sh` default shell and validate runtime settings for command timeout, output cap, and shell history size.
+
+### Fixed
+
+- Normalized ordinary PTY line endings in `ekwsh` command output so transcripts avoid stray carriage returns.
+- Added `ekwsh` timeout and output-limit enforcement for external commands using the shared local command runner.
+- Consolidated workspace shell command execution on a shared local command runner with timeout, cancellation, bounded capture, and optional streaming support.
+- Fixed `ekwsh` shell output sanitization so unsafe terminal controls are stripped before command output is shown while SGR color is preserved.
+- Split Vibe editor insert/readline key handling into a focused mixin without changing editor behavior.
+- Consolidated compaction message-field reads through the shared message access helper.
+- Consolidated RPC transcript tool metadata normalization with tool event metadata so tool names, args, diffs, and changed files stay aligned.
+- Fixed RPC tool capabilities so `changedFiles` is advertised when emitted in tool results.
+- Removed a stale `count-tests` CLI branch that could crash instead of treating the input as a prompt.
+- Fixed tab failures and cancellations so red tab states always emit a runtime message explaining what happened.
+- Fixed model and reasoning changes from CLI/RPC settings so active session runtime metadata is persisted before the next turn.
+- Fixed `context_for_task` so candidate files with no task matches return a clear no-match message instead of only a header.
+- Fixed workspace file tools so expected filesystem permission and path-type errors are returned as tool errors instead of aborting a turn.
+- Fixed composer `Ctrl+C` so it no longer exits the app when no process is running.
+- Fixed the Git diff viewer so `Ctrl+C` and terminal-forwarded `Cmd+C` copy selected text.
+- Fixed pasted or dropped shell-escaped image paths so the composer hides the path text after adding the image badge.
+- Fixed `read_skill` tool transcript rendering so skill frontmatter starts on the line after the tool label.
+- Fixed built-in editor soft-wrap vertical movement so moving up or down preserves the visual column across wrapped visual rows and logical line boundaries.
+
 ## [0.72.0] - 2026-06-28
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kward (0.72.0)
+    kward (0.73.1)
       base64
       nokogiri
       tiktoken_ruby
@@ -146,7 +146,7 @@ CHECKSUMS
   html-proofer (5.2.1) sha256=fdd958a7cbf9c3255fb96fe7cfc4e611f64e2706e469488a3326309ad007d2fd
   io-event (1.16.2) sha256=9f9cb0a96ea5c3850a672606c65f27bc96d7621399ef6196acbfe2be0cd1279c
   json (2.19.9) sha256=9b9025b7cdddafa38d316eca0b2358488e42d417045c1b90d216a9fefe46b79a
-  kward (0.72.0)
+  kward (0.73.1)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
   metrics (0.15.0) sha256=61ded5bac95118e995b1bc9ed4a5f19bc9814928a312a85b200abbdac9039072
   minitest (6.0.6) sha256=153ea36d1d987a62942382b61075745042a2b3123b1cd48f4c3675af9cc7d6f1

data/doc/configuration.md

@@ -58,7 +58,7 @@ aliases:
 
 `env` values are applied when shell mode starts, after Kward's conservative color defaults. Keys must look like environment variable names (`A_Z`, digits after the first character, and underscores); invalid keys are ignored. Values are converted to strings.
 
-`aliases` expand the first word of a command once. For example, `ll lib` runs `ls -la lib`. Built-in `ekwsh` commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `clear`, and `exit` take precedence over aliases. Run `alias` inside `ekwsh` to list configured aliases. Aliases are also included in command-name Tab completion.
+`aliases` expand the first word of a command once. For example, `ll lib` runs `ls -la lib`. Built-in `ekwsh` commands such as `cd`, `pwd`, `export`, `unset`, `alias`, `clear`, `pty`, and `exit` take precedence over aliases. Run `alias` inside `ekwsh` to list configured aliases. Aliases are also included in command-name Tab completion.
 
 ## Provider and model settings
 

data/doc/editor.md

@@ -32,12 +32,33 @@ For a nested project tree, run:
 
 In the tree browser, use `↑`/`↓` to move, `←`/`→` to collapse or expand directories, `Enter` to toggle a directory or open a file, `Tab` or `/` to search, `@` to insert the selected file as an `@path` mention, and `Esc` to close. When you open a file from `/files`, quitting the editor returns to the browser at the same position.
 
+For an unsaved buffer, open a scratchpad:
+
+```text
+/scratchpad
+/scratchpad markdown
+/scratchpad ruby
+```
+
+Scratchpads start as virtual editor buffers named `scratchpad.txt`, `scratchpad.md`, or `scratchpad.rb`. In Vibe mode, save one to a real file with `:w filename`.
+Ruby scratchpads can run with `:run` in Vibe mode or `Ctrl+R` in Modern mode; Kward executes the buffer and writes combined output after `__END__`, replacing any previous output there.
+
+```ruby
+puts "foo"
+
+__END__
+foo
+```
+
+The next run receives the current `__END__` section as Ruby `DATA`, then replaces it with the new output.
+
 You can also type a relative path yourself and press `Enter`. If the file does not exist, Kward asks whether to create it.
 
 A few things to know:
 
 - `$` only opens the editor when it is the first character in the composer.
-- Once a file opens, the composer becomes the editor.
+- `/scratchpad` opens a plain-text scratchpad; pass `markdown` or `ruby` to pick another mode.
+- Once a file or scratchpad opens, the composer becomes the editor.
 - Save or quit to return to normal chat.
 - If the file changed on disk while you were editing, Kward asks before overwriting it.
 - If you quit with unsaved changes, Kward asks before discarding them.
@@ -51,7 +72,7 @@ $doc/editor.md
 1. Type `$doc/editor.md` in the composer.
 2. Pick the file from the matching results, or press `Enter` if the path is already complete.
 3. Edit the file.
-4. Save with `Ctrl+S` in Modern mode, `C-x C-s` in Emacs mode, or `:w` in Vibe mode.
+4. Save with `Ctrl+S` in Modern mode, `C-x C-s` in Emacs mode, or `:w` in Vibe mode. For an unsaved scratchpad in Vibe mode, use `:w filename`.
 5. Quit with `Ctrl+Q`, `C-x C-c`, or `:q`.
 6. Continue chatting with Kward.
 

data/doc/git.md

@@ -54,6 +54,7 @@ Useful keys in the diff viewer:
 | `Page Up` / `Page Down` | Scroll by a page. |
 | `Home` / `End` | Move within the current line. |
 | `/` or `Ctrl+F` | Search within the diff. |
+| `Ctrl+C` / `Cmd+C` | Copy the current selection. |
 | `Enter` | Confirm the current search. |
 | `Esc` | Cancel search, or close the diff viewer. |
 | `Ctrl+Q` | Close the diff viewer. |

data/doc/rpc.md

@@ -50,7 +50,7 @@ Result fields:
 Detailed capability fields include:
 
 - `transcript`: Tauren transcript format support, including normalized messages, image/tool support, compaction summaries, and restored assistant reasoning as Pi-compatible `thinking` content blocks.
-- `sessions`: explicit RPC session mode, JSONL persistence, supported session methods, startup auto-resume capability/default, immediate transcript support for auto-resume, RPC list support, supported linear-session fork methods, supported compaction, supported tree navigation with labels and branch summarization, and explicit unsupported import/update features.
+- `sessions`: explicit RPC session mode, JSONL persistence, supported session methods, startup auto-resume capability/default, immediate transcript support for auto-resume, RPC list support, supported linear-session fork methods, supported compaction, supported tree navigation with labels and branch summarization, explicit unsupported import support, and unsupported live session updates reported with `notification: "session/updated"`.
 - `turns`: async turn mode, per-session concurrency, provider-gated native busy-input steering, queued follow-up input, best-effort cancellation, and recent in-memory event replay behavior.
 - `events`: `turn/event` notification details, assistant/reasoning event names, normalized tool metadata, diff result support, configured workspace guardrail status, focused context and context-budget stats tool support, and explicit unsupported shell changed-file detection/session update flags.
 - `attachments`: supported input attachment contract for `turns/start`, with accepted base64 image MIME types and a stable max byte value.
@@ -405,7 +405,7 @@ Params:
 
 - `sessionId`: active RPC session ID.
 - `settingId`: currently `defaultModel` or `defaultThinkingLevel`.
-- `value`: setting value. `defaultModel` accepts `Provider/model-id` and preserves slashes after the provider separator.
+- `value`: setting value. `defaultModel` accepts a structured object such as `{ "provider": "OpenRouter", "model": "anthropic/claude-sonnet-4.5" }`. For compatibility, it also accepts `Provider/model-id` strings and preserves slashes after the provider separator.
 
 Applies the setting live by updating config and refreshing client config. Unsupported setting IDs are rejected.
 

data/doc/shell.md

@@ -12,7 +12,7 @@ This makes it good for:
 - using project aliases,
 - keeping command output visible beside the current Kward session.
 
-It is not intended for full-screen interactive programs such as `vim`, `less`, `top`, `ssh`, or REPLs.
+Use `/pty <command>` when you intentionally want to hand the terminal to a full-screen interactive command such as `less`.
 
 ## Start shell mode
 
@@ -47,7 +47,7 @@ or press Ctrl+D on an empty shell prompt.
 
 ## How commands run
 
-`ekwsh` runs each command through your configured shell using the shell's `-c` mode. It uses `$SHELL` when set, otherwise `/bin/sh`. The shell is intentionally not started as a login shell so Kward-managed environment values, such as configured PATH entries, are not overwritten by login startup files.
+`ekwsh` is POSIX-oriented and runs each command through `/bin/sh` using the shell's `-c` mode by default. You can configure another POSIX-compatible shell in `ekwsh.yml`. The shell is intentionally not started as a login shell so Kward-managed environment values, such as configured PATH entries, are not overwritten by login startup files.
 
 The current directory and exported environment are tracked by Kward between commands, so this works as expected:
 
@@ -61,7 +61,9 @@ unset FOO
 
 `cd` changes only the embedded shell's current directory. It does not change Kward's workspace root or the process directory used by the rest of Kward.
 
-Shell output is shown in the transcript area, but it is not added to the AI conversation history.
+Shell output streams into the transcript area as commands run, but it is not added to the AI conversation history. Simple assignment-only commands such as `FOO=bar` persist into the embedded shell environment for later commands.
+
+Shell commands are persisted in a separate workspace-scoped shell history. They do not share the normal Kward prompt history used for chat prompts. The shell history limit is controlled by `history_limit` in `ekwsh.yml`.
 
 ## Built-ins
 
@@ -71,9 +73,10 @@ Shell output is shown in the transcript area, but it is not added to the AI conv
 | --- | --- |
 | `cd [dir]` | Change the embedded shell directory. Supports `cd`, `cd -`, and normal relative paths. |
 | `pwd` | Print the embedded shell directory. |
-| `export KEY=value` | Set an environment variable for later commands. |
+| `export KEY[=value]` | Set or mark an environment variable for later commands. `export` and `export -p` list variables. |
 | `unset KEY` | Remove an environment variable from later commands. |
-| `alias [name]` | List configured aliases, or show specific configured aliases. |
+| `alias [name]` | List configured aliases, show specific configured aliases, or set `alias name=value`. |
+| `unalias name` / `unalias -a` | Remove configured aliases. |
 | `clear` | Clear Kward's visible transcript. |
 | `exit` / `logout` | Leave shell mode. |
 
@@ -92,7 +95,7 @@ This means each tab can have its own:
 - visible shell transcript,
 - command prompt state.
 
-Kward's normal tab-switching shortcuts continue to work in shell mode.
+Kward's normal tab-switching shortcuts continue to work in shell mode. If you switch tabs while a shell command is running, Kward cancels that foreground command and requeues the tab action so the TUI can switch cleanly.
 
 ## Tab completion
 
@@ -123,7 +126,14 @@ cat my<Tab>
 # => cat my\ file.txt
 ```
 
-If there are multiple candidates, Kward applies any common prefix. When there is no longer common prefix, it prints a compact candidate list in the transcript.
+Quoted path tokens are completed in the same quoting style:
+
+```sh
+cat "my<Tab>
+# => cat "my file.txt
+```
+
+If there are multiple candidates, Kward applies any common prefix. When there is no longer common prefix, it prints a compact candidate list in the transcript. Command-name completion caches `$PATH` executables and refreshes when `PATH` changes through shell assignment, `export`, or `unset`.
 
 ## Colors and ANSI output
 
@@ -168,6 +178,11 @@ If `KWARD_CONFIG_PATH` points to another config file, `ekwsh.yml` is read from t
 Example:
 
 ```yaml
+shell: /bin/sh
+# timeout_seconds: 300
+# max_output_bytes: 1048576
+# history_limit: 1000
+
 env:
   FORCE_COLOR: "1"
   CLICOLOR_FORCE: "1"
@@ -181,6 +196,19 @@ aliases:
   t: "bundle exec ruby -Itest"
 ```
 
+### Runtime settings
+
+`ekwsh` accepts these top-level runtime settings:
+
+| Setting | Default | What it does |
+| --- | --- | --- |
+| `shell` | `/bin/sh` | Absolute path to the POSIX-compatible shell used with `-c`. Invalid or relative paths fall back to `/bin/sh`. |
+| `timeout_seconds` | `300` | Maximum runtime for one command. |
+| `max_output_bytes` | `1048576` | Maximum captured output for one command. |
+| `history_limit` | `1000` | Maximum persisted shell history entries per workspace. |
+
+When a command exceeds `timeout_seconds`, `ekwsh` terminates it and reports the timeout. When command output exceeds `max_output_bytes`, `ekwsh` terminates the command, keeps bounded output, and reports the output limit. Press Ctrl+C while a command is running to terminate that command and return to the shell prompt without exiting Kward.
+
 ### Environment variables
 
 `env` values are applied when shell mode starts, after Kward's conservative color defaults.
@@ -252,6 +280,25 @@ alias ll gs
 
 Aliases also appear in command-name Tab completion.
 
+## Interactive PTY passthrough
+
+Use `/pty <command>` for commands that need to own the terminal temporarily, such as pagers:
+
+```text
+/pty git log
+```
+
+Inside `/shell`, use the `pty` built-in so the command inherits the embedded shell's current directory and environment:
+
+```sh
+pty git log
+pty vim README.md
+```
+
+Kward runs the command in a PTY, forwards your keyboard input to the process, and streams the process output directly to the terminal. This lets tools such as `less` receive keys like Space, `/`, `n`, and `q` normally. When the command exits, Kward restores its prompt and records only a short session summary in the transcript instead of raw full-screen terminal control output.
+
+`/pty` and shell `pty` are explicit on purpose. Normal `/shell` commands remain captured and transcript-friendly; `pty` is for commands where the child process should temporarily own the terminal.
+
 ## `/shell` versus `!command`
 
 Kward has two ways to run local commands yourself:
@@ -279,8 +326,7 @@ Current limitations:
 - no job control,
 - no persistent shell functions,
 - no shell startup file sourcing,
-- no full-screen terminal applications,
 - no native readline from your login shell,
-- command output is captured through pipes, not a PTY.
+- normal `/shell` command output is transcript-sanitized rather than treated as a full terminal UI.
 
-Some tools only emit color or progress UI when stdout is a real terminal. Prefer explicit command flags such as `--color=always` when needed.
+External `/shell` commands run under a minimal PTY so terminal-aware tools can detect TTY output and terminal width. Full-screen interactive programs should still use explicit `/pty <command>` passthrough.

data/doc/usage.md

@@ -78,7 +78,7 @@ For several commands, enter the embedded Kward shell:
 /shell
 ```
 
-`/shell` opens `ekwsh`, a Kward-native command mode. Kward keeps the tab bar, composer editing, and transcript rendering while each command runs through your configured shell. Built-ins such as `cd`, `pwd`, `export`, `unset`, `alias`, `clear`, and `exit` maintain shell-mode state between commands. Plain Tab completes built-in command names, configured aliases, executables from `$PATH`, and file paths from the shell's current directory; `cd` completion suggests directories only. `ekwsh` preserves safe ANSI SGR color/style output while stripping terminal-control sequences that could corrupt the TUI, and sets conservative color-friendly environment defaults such as `CLICOLOR=1`, `COLORTERM=truecolor`, and `TERM=xterm-256color` when needed. It does not force color by default; set `FORCE_COLOR`, `CLICOLOR_FORCE`, or command-specific flags such as `--color=always` if you want more aggressive color output. You can set global shell env vars and aliases in `~/.kward/ekwsh.yml`; see [Configuration](configuration.md). It is intended for command output, not full-screen interactive programs such as editors or pagers.
+`/shell` opens `ekwsh`, a Kward-native command mode. Kward keeps the tab bar, composer editing, and transcript rendering while each command runs through your configured shell. Built-ins such as `cd`, `pwd`, `export`, `unset`, `alias`, `clear`, `pty`, and `exit` maintain shell-mode state between commands. Plain Tab completes built-in command names, configured aliases, executables from `$PATH`, and file paths from the shell's current directory; `cd` completion suggests directories only. `ekwsh` preserves safe ANSI SGR color/style output while stripping terminal-control sequences that could corrupt the TUI, and sets conservative color-friendly environment defaults such as `CLICOLOR=1`, `COLORTERM=truecolor`, and `TERM=xterm-256color` when needed. Use `pty git log` or `/pty git log` when you intentionally want to hand the terminal to an interactive tool such as `less` or `vim`. You can set global shell env vars and aliases in `~/.kward/ekwsh.yml`; see [Configuration](configuration.md).
 
 ## Shell commands
 
@@ -114,8 +114,10 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/model` | choose the active model. |
 | `/reasoning` | choose reasoning effort. |
 | `/git` | review uncommitted changes, stage files, and commit. |
+| `/diff` | open the file changes recorded in the current session. |
 | `/files` | browse project files in a nested tree and open them in the editor. |
 | `/shell` | run workspace commands in the embedded Kward shell. |
+| `/pty <command>` | hand the terminal to an interactive command such as `git log`/`less` or `vim`. |
 | `/settings` | configure prompt overlays. |
 | `/status` | see session, model, and context status. |
 | `/new` | start a fresh session in the current tab. |
@@ -141,10 +143,34 @@ Slash commands run local actions in the current session. Most do not send a prom
 | `/redraw` | fix terminal drawing after resize or glitches. |
 | `/reload` | reload installed plugins. |
 | `/workers` | open the experimental worker pipeline (`new`, `do <task>`, or `list`). |
+| `/queue` | manage the experimental tab-backed worker queue (`add`, `list`, `open <id>`, `run`, `suspend <id>`, or `resume <id>`). |
 | `/exit` | leave Kward. |
 
 Prompt templates and plugins can add more slash commands.
 
+### Experimental tab-backed worker queue
+
+Start Kward with `--experimental-workers` to try the tab-backed worker queue. The queue is an MVP for turning an existing tab/session into implementation work that can be reviewed later.
+
+Typical flow:
+
+```text
+/plan Add retry handling to webhook delivery
+/queue add
+/queue run
+/queue open <id>
+```
+
+`/queue add` stores the current tab session as a queued worker job. `/queue run` drains queued jobs one at a time. Each job continues its saved session as an implementation worker, starts only from a clean git workspace, commits any resulting changes, and then becomes `ready_for_review`. Use `/queue open <id>` to inspect the worker session, test the feature yourself, and continue the same session if a follow-up fix is needed.
+
+Current MVP limitations:
+
+- The queue is manual: run it with `/queue run` when you want it to work.
+- Jobs run sequentially and stop when one becomes `blocked` or `failed`.
+- A job will not start if the workspace is dirty; clean, commit, or stash your changes first.
+- `/queue suspend <id>` and `/queue resume <id>` provide explicit stash-based parking primitives, but automatic foreground-tool-triggered yielding is not wired yet.
+- The queue is experimental and stores metadata locally in Kward's config directory.
+
 ## Prompt history
 
 In interactive mode, Kward keeps prompt history per workspace under `~/.kward/history/`. Press Up/Down to recall previous prompts across restarts.

data/lib/kward/ansi.rb

@@ -1,11 +1,13 @@
 # Namespace for the Kward CLI agent runtime.
 module Kward
-  # ANSI color and terminal capability helpers.
+  # ANSI SGR styling and terminal-text helpers.
+  #
+  # Terminal control output sequences live in `TerminalSequences`, and input key
+  # sequences live in `TerminalKeys`. This module owns text-level concerns:
+  # colorizing strings, stripping/sanitizing escape sequences, visible wrapping,
+  # and lightweight Markdown rendering for terminal output.
   module ANSI
-    ESCAPE_PATTERN = /\e\[[0-9;?]*[ -\/]*[@-~]/.freeze
     SGR_PATTERN = /\e\[[0-9;:]*m/.freeze
-    OSC_PATTERN = /\e\][^\a]*(?:\a|\e\\)/m.freeze
-    STRING_ESCAPE_PATTERN = /\e[P_X^][\s\S]*?\e\\/m.freeze
     STYLES = {
       reset: 0,
       bold: 1,
@@ -52,13 +54,24 @@ module Kward
     end
 
     def strip(text)
-      text.to_s.gsub(ESCAPE_PATTERN, "")
+      strip_control_sequences(text)
     end
 
+    # Removes terminal escape/control sequences while preserving visible text.
+    def strip_control_sequences(text)
+      scan_escape_tokens(text).each_with_object(+"") do |token, stripped|
+        stripped << token[:text] unless token[:escape]
+      end
+    end
+
+    # Drops unsafe terminal controls from transcript text while preserving SGR color.
     def sanitize_transcript(text)
-      string = text.to_s.gsub(OSC_PATTERN, "").gsub(STRING_ESCAPE_PATTERN, "")
-      string.gsub(/\e(?:\[[0-9;:?]*[ -\/]*[@-~]|.)/m) do |sequence|
-        sequence.match?(SGR_PATTERN) ? sequence : ""
+      scan_escape_tokens(text).each_with_object(+"") do |token, sanitized|
+        if token[:escape]
+          sanitized << token[:text] if token[:text].match?(SGR_PATTERN)
+        else
+          sanitized << token[:text]
+        end
       end
     end
 
@@ -67,28 +80,27 @@ module Kward
       rows = []
       current = +""
       visible_width = 0
-      string = text.to_s
-      index = 0
 
-      while index < string.length
-        if string[index] == "\e" && (match = string[index..].match(/\A\e\[[0-9;:]*m/))
+      scan_escape_tokens(text).each do |token|
+        if token[:escape]
+          next unless token[:text].match?(SGR_PATTERN)
+
           if current.empty? && rows.any?
-            rows[-1] << match[0]
+            rows[-1] << token[:text]
           else
-            current << match[0]
+            current << token[:text]
           end
-          index += match[0].length
           next
         end
 
-        char = string[index]
-        current << char
-        visible_width += 1
-        index += 1
-        if visible_width >= line_width
-          rows << current
-          current = +""
-          visible_width = 0
+        token[:text].each_char do |char|
+          current << char
+          visible_width += 1
+          if visible_width >= line_width
+            rows << current
+            current = +""
+            visible_width = 0
+          end
         end
       end
 
@@ -96,6 +108,33 @@ module Kward
       rows
     end
 
+    # Splits text into visible chunks and terminal escape sequence chunks.
+    def scan_escape_tokens(text)
+      string = text.to_s
+      tokens = []
+      index = 0
+      while index < string.length
+        if string[index] == "\e" && (escape = escape_sequence_at(string, index))
+          tokens << { text: escape, escape: true }
+          index += escape.length
+          next
+        end
+
+        next_escape = string.index("\e", index) || string.length
+        tokens << { text: string[index...next_escape], escape: false } if next_escape > index
+        index = next_escape
+      end
+      tokens
+    end
+
+    def escape_sequence_at(string, index)
+      chunk = string[index..]
+      chunk.match(/\A\e\][^\a]*(?:\a|\e\\)/m)&.[](0) ||
+        chunk.match(/\A\e[P_X^][\s\S]*?\e\\/m)&.[](0) ||
+        chunk.match(/\A\e\[[0-9;:?]*[ -\/]*[@-~]/)&.[](0) ||
+        chunk[0, 2]
+    end
+
     def markdown(text, enabled: enabled?)
       string = text.to_s
       lines = string.lines(chomp: true)

data/lib/kward/cli/plugins.rb

@@ -88,7 +88,7 @@ module Kward
       def builtin_slash_commands
         return BUILTIN_SLASH_COMMANDS if experimental_workers_enabled?
 
-        BUILTIN_SLASH_COMMANDS.reject { |command| command[:name] == "workers" }
+        BUILTIN_SLASH_COMMANDS.reject { |command| %w[workers queue].include?(command[:name]) }
       end
 
       def builtin_slash_command_names

data/lib/kward/cli/rendering.rb

@@ -318,7 +318,10 @@ module Kward
       end
 
       def tool_summary_display_text(summary)
-        summary.to_s.sub("\n", "\n\n")
+        text = summary.to_s
+        return text if text.start_with?("read_skill:\n")
+
+        text.sub("\n", "\n\n")
       end
 
       def start_stream_block(label)