@sagmans/dsh-tui 0.3.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 Interactive terminal (TUI) surface for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): use `dsh` in a terminal instead of a browser.
 
-Status: **v1 feature-complete; published on npm as `@sagmans/dsh-tui`.** The surface owns the alternate screen, streams assistant text as markdown, renders every tool's own card, answers approvals and questions, restores and names stored conversations, switches model mid-session, runs any of the four shipped agent modes and switches between them before a session's first turn, reads a child agent's conversation in place, keeps the goal, plan mode, todo list, delegations, and background jobs above the editor with a status line below it, and hands the terminal back on every graceful exit. Publication is tag-driven with GitHub OIDC provenance and no stored npm token; see [RELEASE.md](RELEASE.md).
+Status: **v1 feature-complete; published on npm as `@sagmans/dsh-tui`.** The surface owns the alternate screen, streams assistant text as markdown, renders every tool's own card, answers approvals and questions, restores and names stored conversations, switches model mid-session, runs any of the four shipped agent modes and switches between them before a session's first turn, reads a child agent's conversation in place, keeps the goal, plan mode, todo list, delegations, and background jobs above the editor with a status line below it, nudges an agent whose plan has aged without an update, parks and restores prompt drafts per working directory, and hands the terminal back on every graceful exit. Publication is tag-driven with GitHub OIDC provenance and no stored npm token; see [RELEASE.md](RELEASE.md).
 
 ## Install
 
@@ -130,6 +130,9 @@ moves any of them — see [Keys](#keys).
 | Ctrl+Y | show or hide the calls a PTC program dispatched: one two-space-indented entry per call under its `run_code` card, named and argued from the tool's own header and wrapped at the screen edge; shown by default |
 | Shift+Tab | expand or fold the reasoning behind an answer: folded, the row names itself, its token count, and the key; opened, it adds the thought |
 | Ctrl+T | pick the reasoning effort for the next step |
+| Ctrl+R | reverse-search recorded prompts: the list opens filtered by whatever is in the bar, `enter` puts one back, `esc` keeps the draft |
+| Ctrl+X then S | stash the current draft |
+| Ctrl+X then L | open this directory's stashed drafts |
 | Ctrl+X then M | open the model picker |
 | Ctrl+X then Y | copy the last answer to the clipboard |
 | `y` / `n` / Esc | allow once, reject, or cancel a pending approval |
@@ -160,23 +163,33 @@ moves any of them — see [Keys](#keys).
 | `/export [path]` | write the visible transcript as markdown (default `dsh-session-<id>.md`) |
 | `/resume` | open another stored session without leaving the terminal |
 | `/clear` | clear the visible transcript |
+| `/history` | show how many prompts are recorded and where the file is |
+| `/history clear` | forget every recorded prompt, reporting how many went |
 | `/theme` | list every styled element and the value in force |
 | `/keys` | list every action and the keys in force; `/keys <layer>` narrows it (see [Keys](#keys)) |
+| `/stash <draft>` | park the text given after the command (`ctrl+x` then `s` parks the editor) |
+| `/stash-pop [index\|id]` | put a stashed draft into the editor and remove it (newest by default) |
+| `/stash-apply [index\|id]` | put a stashed draft into the editor and keep it |
+| `/stash-list` | pick from this directory's stashed drafts; `enter` pops the marked one |
+| `/stash-drop [index\|id]` | delete a stashed draft without using it |
+| `/stash-clear` | delete every stashed draft for this directory, after a confirmation |
 | `/quit` | leave and print the resume command |
 
 `Ctrl+X` starts a chord. For the next two seconds the footer leads with the
 prefix alone — enough to say that a key is waiting, without reciting the map —
 and a key that finishes nothing is typed as usual rather than swallowed, so a
 prefix pressed by accident costs nothing; `/help` lists the chords, `m` for the
-model picker, `p` for plan mode, and `y` for the last answer.
+model picker, `p` for plan mode, `y` for the last answer, `s` to stash the
+draft, and `l` for the stashes.
 `keys.chord.prefix: alt+x` starts the chord with another key — or with a list of
 them, as so many ways in — and `prefixWindow: 0` waits for the next key instead
 of lapsing; every second key is a row of its own (`chord.model`, `chord.plan`,
-`chord.copy`), so a chord can be respelled whole. A prefix that is not a modifier chord, that
+`chord.copy`, `chord.stash`, `chord.stashes`), so a chord can be respelled whole. A prefix that is not a modifier chord, that
 the surface or the prompt bar already answers (`ctrl+c`, `ctrl+s`), or that the
 terminal keeps (`ctrl+q`) is refused with the reason, and the shipped keymap
 stays in force. The chords themselves are the commands they stand for: `m`, `p`,
-and `y` ask the same dispatcher `/model`, `/plan`, and `/copy` do. Plan mode is
+`y`, `s`, and `l` ask the same dispatcher `/model`, `/plan`, `/copy`, `/stash`,
+and `/stash-list` do. Plan mode is
 the one pair that cannot share a name: `/plan` only enters, so the chord names
 `/plan off` instead when the agent is in plan mode — or is waiting for the turn
 boundary to become so — and reads that state from the plan package rather than
@@ -186,8 +199,81 @@ An approval or a question draws inline above the editor and takes the keyboard.
 
 While a turn runs, a prompt submitted into the editor waits in the agent's own inbox instead of disappearing: it is drawn above the editor in the input bar's own frame, faint and italic, and moves into the transcript when the agent takes it — where it keeps that frame in the prompt's own mint shade, so what the reader typed is never mistaken for what the agent said. `editor.queued` and `editor.queued.more` restyle or hide the waiting rows; `transcript.user` restyles the submitted prompt.
 
+Every submitted line is also kept in a global prompt history at
+`$DSH_HOME/prompt-history.json`. Typing the start of a prompt that was sent
+before draws the rest of the newest match after the cursor in a faint shade.
+`Ctrl+E` takes the whole suggestion and the word-movement key takes the next
+word, and both keys fall back to their old meaning the moment nothing is
+offered. The history is deliberately global — the same prompt is useful in
+every checkout — so nothing records a directory. An exact repeat moves to the
+front instead of being stored twice. `history.ghost: false` keeps reverse
+search but stops drawing the suggestion, `history.enabled: false` stops
+recording and offering, and `history.maxEntries` bounds the file. A file this
+build cannot parse is left untouched and writes are refused, so a newer format
+is never overwritten; `/history` names it and the count, and `/history clear`
+forgets everything.
+
 Any other `/command` goes to the command registry, so `/plan`, `/compact`, `/goal`, and `/feedback` behave as they do on the other surfaces.
 
+## Prompt stash
+
+`ctrl+x` then `s` parks the draft the editor is holding and clears it;
+`/stash <draft>` parks a draft typed on the command line. A bare `/stash` only
+says so, because submitting a command consumes the line it was typed on and there
+is nothing left of the draft to park. `/stash-pop` puts a parked draft back and
+removes it, so a prompt written for the wrong moment survives a restart instead
+of being retyped or sent; `l` opens the list of them. A stash belongs to the exact
+working directory, so the drafts parked in one checkout never appear in another;
+the footer shows `stash N` while any are waiting, ranked above the context and
+cache numbers it shares a row with.
+
+A selector is the number the list shows in brackets — `0` is the newest — or the
+entry's own id; leaving it out takes the newest. `apply` and `pop` refuse to
+overwrite a draft already in the editor, because losing an unsent prompt to a
+restore is the one outcome the feature exists to prevent. They refuse while a
+question is borrowing the bar for the same reason: a draft written into an answer
+would be sent as one. `pop` writes the editor first and removes the entry second,
+so a crash between the two leaves the draft in the bank rather than only in a
+terminal that is gone.
+
+Nothing is cleared until the write has landed. A refusal — no room left, a bank
+past its cap, another writer holding the lock — leaves the draft in the bar,
+including a draft typed after `/stash`, which is written back into the bar before
+the write is attempted. The bar is only cleared while it still holds that same
+draft and no question has borrowed it, so an answer typed during the write is
+never wiped by a stash finishing.
+
+The bank is one JSON file per directory under `$DSH_HOME/tui-stash`, written with
+owner-only permissions (`0700` directory, `0600` file) through a no-follow open,
+and every directory the path passes through must be owned by the reader (or by
+root) and not writable by anyone else — the sticky bit is the only exception,
+since it keeps renaming to an entry's owner. Links are walked one hop at a time,
+with `..` left for the filesystem to resolve against what the link points at, and
+a link this user does not own ends the walk: a chain that jumps through a shared
+directory is refused at the directory it jumped through. A directory
+that another user or a group member could redirect the storage through is refused
+rather than trusted, which is also why a group-writable home directory fails the
+stash with the offending path named. Every update is a locked read-modify-write
+and an atomic temp-and-rename, so two surfaces in the same directory cannot lose
+each other's entries; reclaiming a lock whose owner is gone is serialized on a
+per-bank claim file, and the removal only applies to the lock it judged, so a
+holder that released in between cannot have its successor's live lock deleted. A
+contender never deletes a lock it did not publish, so losing the name to a
+successor costs a retry rather than the successor's turn.
+
+A bank whose working directory is not this one, or whose bytes do not parse, is
+moved aside as `<name>.corrupt-<time>` and reported with its path — including when
+the directory holding the copy could not be synced. A bank written by a newer
+format, or one past the size cap, is refused in place rather than moved, because
+neither is corruption. A storage directory a save had to create is flushed
+through the directory that names it before the save reports anything. If that
+flush fails, the empty directories are taken back so the retry starts clean; a
+directory another surface has already saved into is left exactly as it is, because
+an entry left unflushed costs durability while a removed bank costs the draft. Drafts are never written to a session log, and control and
+Unicode bidi controls are stripped when a draft is stored and again when it is
+read, so a hand-edited bank cannot park a terminal escape or a reordering trick in
+the bar.
+
 ## Settings
 
 Every styled element is a named token with a shipped default, and every key is
@@ -205,6 +291,10 @@ dsh-tui:
     prompt.submit: [ctrl+enter, alt+enter, ctrl+s]
     surface.effort: ctrl+t    # one key, or a list of them
     tui.editor.yank: ctrl+y   # any action the library draws, by the id /keys prints
+  history:
+    enabled: true             # record prompts and offer them back (default true)
+    ghost: true               # draw the dimmed completion; reverse search stays either way (default true)
+    maxEntries: 2000          # prompts kept, newest first (1-20000, default 2000)
   palette:
     muted: '#5c5c5c'          # one shade quiets every receding element
   tokens:
@@ -230,6 +320,13 @@ card alone instead. `Ctrl+Y` toggles the same choice for the current session,
 and an edit to the document re-seeds it. An unknown key or value is
 refused with a notice naming it, so a typo cannot quietly do nothing.
 
+The `history` block tunes the prompt history. `enabled: false` stops recording
+and offering it; `ghost: false` keeps reverse search but stops the dimmed
+completion; `maxEntries` bounds the file, and an exact repeat moves to the
+front rather than being stored twice. `editor.ghost` styles the suggestion, and
+`NO_COLOR` or `--no-color` suppresses it entirely, because a suggestion the
+reader cannot see but could still accept is worse than none.
+
 A reply whose fenced block names `mermaid` is drawn as terminal box art instead
 of source, laid out at the width the transcript has. `mermaid: streaming` (the
 default) draws a diagram while the reply is still arriving, `final` waits for
@@ -339,6 +436,7 @@ The package is a Cordis plugin bundle that stacks over `@deepseek-ai/dsh-base`:
 - `@deepseek-ai/dsh-agent-presets` is the roster of modes, holding the id a session starts in when nobody names one.
 - `@deepseek-ai/dsh-code-runtime-worker-thread` and `@deepseek-ai/dsh-cordis-host-runner` are the host machinery PTC mode and creator mode need; only the Web bundle shipped them, so a terminal profile has to mount them to offer those modes at all.
 - `@sagmans/dsh-tui` owns the terminal: it creates or resumes one agent through `ctx.agents`, folds `session/event` into transcript rows and work state, renders them with `@earendil-works/pi-tui`, and releases the terminal on exit, on a boot failure, and on a signal.
+- `@sagmans/dsh-tui/todo-guard` is the one advisory row this bundle adds to the agent plane: it watches the harness's own `todos` and `plan` projections and rides the next tool result with a reminder when a plan ages. See [Todo discipline](#todo-discipline).
 
 A question whose id ends in `:secret` declares its typed answer a credential: the bar hides everything but its first and last four characters, and the free-text row a question with options offers is labelled `API KEY`. Wording is not a declaration, because hiding every question that mentions a key would hide answers their authors meant to be read.
 
@@ -352,6 +450,49 @@ A card's header names the tool, then the argument the call was made with — a p
 
 The bundle also takes the base's global agent rows out of the composition, twenty-three of them. Every one is a row the shipped modes supply per session instead, so leaving it mounted registers the same tool names in two layers and doubles each prompt section it owns. What stays mounted is the host: sessions, storage, models, permissions, jobs, and the command registry.
 
+### Todo discipline
+
+The todo tool and its list belong to the agent; this bundle owns the surface and one advisory guard. `@sagmans/dsh-tui/todo-guard` mounts host-plane, reads the harness's own `todos` and `plan` projections, and — when a non-empty list has gone a threshold of model steps without a `todo_write`, or a long turn has produced no list at all — rides the next tool result with a model-visible reminder. It never vetoes a call, never steers a stopped turn, and never adds a prompt section, so its request prefix stays stable across deployments. A reminder costs the loop one extra model step to consume; the per-turn cap bounds that. It stays silent in plan mode, in a mode whose catalog has no `todo_write`, and when the projections are absent.
+
+| Option | Default | Effect |
+|---|---|---|
+| `staleSteps` | `6` | model steps a non-empty open list may age before the guard speaks |
+| `missingListSteps` | `12` | steps in a turn before the guard suggests a first list |
+| `maxRemindersPerTurn` | `3` | hard cap on reminders, and on the extra steps they cost, per turn |
+| `previewItems` | `5` | open items quoted in a reminder; the rest become a count |
+
+Override them from the home-level patch, which outranks the profile's own layers. An id-targeted patch replaces the whole config, so restate every field you keep:
+
+```yaml
+# $DSH_HOME/cordis.patch.yml
+- id: tui-todo-guard
+  config:
+    staleSteps: 4
+    missingListSteps: 12
+    maxRemindersPerTurn: 3
+    previewItems: 5
+```
+
+The list the dock and `/todo` draw follows the same lifetime every other surface shows: it is cleared when the next turn opens, because a fresh task must not inherit the previous turn's checklist.
+
+## Herdr
+
+[Herdr](https://github.com/herdrdev/herdr) is a terminal multiplexer for coding agents. When it starts this surface in one of its panes it exports `HERDR_ENV=1`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH`, and the pane reports what it is doing over that socket — as the agent `dsh`, under the source `custom:dsh-tui`. Away from Herdr (an ordinary terminal, SSH, tmux) the reporter is inert: no socket is opened, and nothing reaches the screen the reader owns.
+
+| This surface | Herdr |
+|---|---|
+| the screen is taken, before any session opens | `idle`, claiming the pane's agent row |
+| `turn/start` | `working` |
+| an approval, a question, or a picker takes the keyboard | `blocked`, with that card's title sent along |
+| the decision settles | `working` if a turn is open, otherwise `idle` |
+| `turn/end` | `idle` |
+| a session opens, resumes, forks, or is switched to | its id and reason, plus the `dsh_session` / `dsh_cwd` pane tokens |
+| exit, signal, or boot failure | `herdr pane release-agent`, so no row is left waiting on a process that is gone |
+
+A wait outranks a running turn: a turn waiting on a human is not making progress, and the wait is the only thing worth acting on from a wall of panes. Reports are sequenced per source, so a delivery that arrives late cannot undo the state the surface already moved past, and a state Herdr is already showing is not sent again. A report is only counted as made when Herdr acknowledges it: one that failed is tried again — soon after, then with a growing wait — and a session identity Herdr never confirmed travels with the next report of any kind. The retry cannot wait for another state change, because the pane may have nothing left to say: a turn that ended while the socket was down produces no further event. States still waiting to be sent are collapsed into the newest one, so a socket that was down for a minute is told where the pane is rather than where it has been. The release carries the next number in that same sequence for the same reason: Herdr reads one that cannot beat the pane's last report as stale, and a stale release leaves the row waiting on a process that is gone. It also stops reporting first — a claim landing after the release would take the row back for a process that is leaving — and the report already on the wire is waited for before the row goes back, because Herdr ignores the release of a pane nothing has claimed yet and that late report would then claim it. What is still waiting behind it is dropped rather than sent.
+
+Herdr persists a session reference only for its own built-in integrations, so this pane's session identity travels as metadata tokens instead: a script or a companion plugin reads them back with `herdr pane get <id>` and resumes that exact conversation with `dsh --profile tui --resume=<id>`. Herdr holds a token value up to 80 characters and shortens anything longer, so a session id or directory that cannot be sent whole has its token cleared instead: a shortened path would read as a different directory, and a pane must not claim one. What Herdr cannot do is identify the process itself — its detection table and its screen rules both name built-in agents only — so a pane that has not reported yet reads as an ordinary pane, and is not yet a target: `herdr agent wait` on it fails with `agent_not_found` until the first report lands. Herdr 0.9.1 also keeps the title that accompanies a `blocked` state without showing it anywhere, so a reader sees the state and reads the card on screen.
+
 ## Development
 
 ```sh
@@ -400,6 +541,10 @@ The automated checks drive a real PTY, but they run on this machine's terminal.
 | a reply carrying a mermaid fence | it draws as box art at the transcript width, with the prose around it untouched |
 | that reply in a terminal narrower than the drawing | the fence stays source, and widening the window draws it without a new turn |
 | `dsh-tui: { mermaid: off }` in `$DSH_HOME/settings.yaml`, then a mermaid reply | the fence stays source; editing the value to `streaming` draws a settled reply without a restart |
+| type the start of a prompt already recorded | the rest of the newest match follows the cursor in a faint shade; `ctrl+e` takes it whole, the word-right key takes one word, and both keys do their old job when nothing is offered |
+| `ctrl+r`, then a fragment | reverse search opens seeded with the bar's draft; `enter` puts a prompt back, `esc` keeps the draft |
+| `dsh-tui: { history: { ghost: false } }`, then type a known prefix | no suggestion is drawn, and `ctrl+r` still searches |
+| `/history clear`, then `/history` | the notice reports the count forgotten, and the second reports `1 prompt recorded` — the check line is itself recorded |
 | `/model` on a configured profile | the picker lists only the configured providers' advertised models, heads itself with the route in force, and typing filters it while later rows stream in; `esc` or Ctrl+C leaves without changing the route, and `enter` chains into the route's reasoning efforts |
 | `/preset` on a fresh session | the picker lists four modes, marks the current one, and the switch survives a resume |
 | `/preset minimal` after a turn | refused, naming the reason; the session keeps the mode it composed with |
@@ -412,6 +557,10 @@ The automated checks drive a real PTY, but they run on this machine's terminal.
 | press `0` on a question, type an answer, press Enter | the editor under row `0` shows the text as it is edited, and the model receives it as that question's answer |
 | type a prompt without sending it, then answer a question | the prompt bar steps aside while the question is open and holds the same prompt again afterwards |
 | `echo hi \| dsh --profile tui` | refuses with a non-zero exit and a message naming the TTY requirement |
+| `/stash`, `/stash-pop` in one terminal | the footer shows `stash 1` after the stash and the draft returns to the editor after the pop |
+| a second `dsh --profile tui` in the same directory | `/stash-list` shows the draft the first terminal parked |
+| `dsh --profile tui` in another directory | `/stash-list` says `no stashed drafts`, even though the first directory still has one |
+| hand-edit `$DSH_HOME/tui-stash/<key>.json` into invalid JSON, then `/stash-list` | the surface reports the quarantine path, starts empty, and leaves the moved file readable |
 | `/quit`, Ctrl+C while idle, `kill -TERM <pid>` | the shell returns with cursor, echo, mouse, and title restored |
 
 ## Releasing
@@ -430,15 +579,18 @@ The workflow stores no npm token: the registry trusts `release.yml` on the `npm-
 - `/model` changes the route and reasoning effort for the running session only. Catalog membership is advisory — an adapter may accept an id it does not advertise, while an explicit effort is checked against the route's own levels before it is applied. The picker offers the routes this deployment configured, not the ones it can prove credentialed: a provider whose key or sign-in is still missing appears like any other, and its first request names the missing credential.
 - Scrolling is the mouse wheel, or the terminal's own scrollback keys where it offers them.
 - A turn that ran longer than ten seconds rings the terminal bell when it ends, because the reader may have walked away; `--no-bell` turns that off.
-- The dock shows the goal, plan mode, the todo items still to do, and any background job or delegation still running; a settled item leaves rather than turns into a completed row. The transcript marks where older history was compacted away. `/plan` toggles plan mode; `/plan <message>` also steers that message, which is the base command's own behaviour.
+- The dock shows the goal, plan mode, the todo items still to do, and any background job or delegation still running; a settled item leaves rather than turns into a completed row, and the list clears when the next turn opens so a fresh task never inherits the previous one's checklist. The transcript marks where older history was compacted away. `/plan` toggles plan mode; `/plan <message>` also steers that message, which is the base command's own behaviour.
 - Background jobs and subagent runs are live process state, not durable events: they disappear when the run ends, and a resumed session starts with an empty board and roster.
 - A card reads its tool's own render intent through the agent whose session is on screen, so a stored session with no live agent — one this process is not running, or a child that has already finished — folds to the generic card instead of the tool's own.
 - Reading a child's conversation does not move the terminal: commands, approvals, and the status line stay with the session you launched, and the transcript is the only thing that switches. The status line carries the way back, read from the map in force, so a remap shows up without reopening the view.
 - Delete is unimplemented: the session store exposes no delete, and the surface does not reach around that seam into its files. `/fork` covers the case that needs it — it branches into a new session and leaves the original alone.
+- The prompt stash holds text only. It does not read Pi's `pi-stash` data, does not migrate an older key format, and keeps no pasted images: a draft larger than 1 MiB, or a bank larger than 16 MiB, is refused rather than stored — the cap is measured on the bytes the file will hold, escapes included, before anything is written, so a refusal cannot leave a bank that saves and then refuses to load. A corrupt bank is quarantined and reported, never repaired in place; a bank from a newer format is refused where it lies, so an older build cannot swallow a newer build's drafts.
 - Approvals and questions render inline and take the keyboard; a question batch is answered in order, and a question that lists options can always be answered with free text on row `0`.
+- Inside Herdr the pane reports its own state, and that report is the only thing that makes it an agent there: Herdr cannot start, resume, or prompt this surface, so launching and resuming stay with `dsh` itself (or a Herdr plugin that runs it).
 - Styling is per element and overridable; see [Settings](#settings). Shipped defaults are emitted as 24-bit colour where the terminal advertises it and degraded to 256 or 16 colours otherwise, so a light or dark terminal still follows its own palette where it has one.
-- Tool text, model text, and file content are escaped before rendering, so a hostile result cannot inject terminal control sequences; the cost is that a literal tab shows as \x09.
+- Tool text, model text, and file content are escaped before rendering, so a hostile result cannot inject terminal control sequences; the cost is that a literal tab shows as \x09. A stashed draft is stripped of control and bidi characters instead, because it is restored into a live editor rather than drawn as text.
 - Mermaid fences draw in assistant replies only, and only at the top level of one: a fence nested in a list, quoted inside another fence, or carried by a prompt, a thought, or a tool card stays source. Author `:::class` styling and diagram links are ignored — the renderer reports what each run is, and the theme decides how it looks.
+- Prompt history is global to this machine, not per project: `$DSH_HOME/prompt-history.json` holds every submitted line, deduplicated exactly, and a file this build cannot parse is left untouched with writes refused so a newer format is never overwritten. Every write re-reads the file under a lock shared by sessions, so a second session's prompts are folded in rather than overwritten, and a lock whose holder stopped is reclaimed or reported instead of guessed at; control characters are spelled out before a prompt is stored. A multiline suggestion draws its first line with `↵` marking the fold. `history.ghost: false` keeps reverse search without the suggestion, `history.enabled: false` stops recording and offering it, and `NO_COLOR`/`--no-color` suppresses the ghost because text the reader cannot see but could still accept is worse than none.
 
 ## License
 

package/cordis.patch.yml

@@ -97,6 +97,20 @@
         color: !!js ctx.tuiStartup.color
         bell: !!js ctx.tuiStartup.bell
 
+    # Advisory todo discipline for every agent this profile runs. The tool and
+    # its list already exist per session; this row only notices when a plan has
+    # aged and rides the next tool result with a reminder. It is host-plane on
+    # purpose: it registers no tool, provides no service, and never gates a
+    # call, so it needs no preset and no realm. `staleSteps` and the rest are
+    # documented in the README and overridable from a profile patch.
+    - id: tui-todo-guard
+      name: '@sagmans/dsh-tui/todo-guard'
+      config:
+        staleSteps: 6
+        missingListSteps: 12
+        maxRemindersPerTurn: 3
+        previewItems: 5
+
     # The roster of agent compositions, and the mode a session starts in when
     # nobody names one. PTC leads because a flagless run should reach every tool
     # through one program rather than one shell call at a time. A profile patch

package/lib/agent/projections.d.ts

@@ -1,12 +1,28 @@
 import type { Context } from '@deepseek-ai/cordis';
+/** One projection read that keeps "not registered" apart from "cannot answer". */
+export type ProjectionRead = {
+    readonly kind: 'state';
+    readonly state: unknown;
+} | {
+    readonly kind: 'unregistered';
+} | {
+    readonly kind: 'unavailable';
+};
 /**
- * One session projection's state.
+ * One session projection's state, with the reason a missing answer is kept.
  *
- * A composition without a projection registry, and a session whose projection
- * unit is not registered, both leave the key simply absent — and the surface
- * reads projections while rendering, where a missing fact may cost a segment
- * but never the session. A registered unit that throws is treated the same way
- * for the same reason.
+ * `stateOf` answers `undefined` only for a key that is not registered; a
+ * composition without a registry, and a registered unit that throws, are the
+ * two cases that leave nothing to read at all. A caller that merely decorates a
+ * screen may collapse them, but one deciding whether it knows enough to speak
+ * must be able to tell them apart.
+ */
+export declare function projectionRead(ctx: Context, session: unknown, key: string): ProjectionRead;
+/**
+ * One session projection's state, or `undefined` whenever there is none to read.
+ *
+ * The surface reads projections while rendering, where a missing fact may cost a
+ * segment but never the session, so every unreadable case collapses here.
  */
 export declare function projectionState(ctx: Context, session: unknown, key: string): unknown;
 /** One projection's state when it is a record. */

package/lib/agent/projections.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"projections.d.ts","sourceRoot":"","sources":["../../src/agent/projections.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOlD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQpF;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAGrC;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhG"}
+{"version":3,"file":"projections.d.ts","sourceRoot":"","sources":["../../src/agent/projections.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOlD,kFAAkF;AAClF,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,CAAA;AAEpC;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAS1F;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAGpF;AAED,kDAAkD;AAClD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAGrC;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGhG"}

package/lib/agent/projections.js

@@ -1,23 +1,34 @@
 /**
- * One session projection's state.
+ * One session projection's state, with the reason a missing answer is kept.
  *
- * A composition without a projection registry, and a session whose projection
- * unit is not registered, both leave the key simply absent — and the surface
- * reads projections while rendering, where a missing fact may cost a segment
- * but never the session. A registered unit that throws is treated the same way
- * for the same reason.
+ * `stateOf` answers `undefined` only for a key that is not registered; a
+ * composition without a registry, and a registered unit that throws, are the
+ * two cases that leave nothing to read at all. A caller that merely decorates a
+ * screen may collapse them, but one deciding whether it knows enough to speak
+ * must be able to tell them apart.
  */
-export function projectionState(ctx, session, key) {
+export function projectionRead(ctx, session, key) {
     const projections = ctx.get('sessionProjections');
     if (projections?.stateOf === undefined)
-        return undefined;
+        return { kind: 'unavailable' };
     try {
-        return projections.stateOf(session, key);
+        const state = projections.stateOf(session, key);
+        return state === undefined ? { kind: 'unregistered' } : { kind: 'state', state };
     }
     catch {
-        return undefined;
+        return { kind: 'unavailable' };
     }
 }
+/**
+ * One session projection's state, or `undefined` whenever there is none to read.
+ *
+ * The surface reads projections while rendering, where a missing fact may cost a
+ * segment but never the session, so every unreadable case collapses here.
+ */
+export function projectionState(ctx, session, key) {
+    const read = projectionRead(ctx, session, key);
+    return read.kind === 'state' ? read.state : undefined;
+}
 /** One projection's state when it is a record. */
 export function projectionRecord(ctx, session, key) {
     const state = projectionState(ctx, session, key);

package/lib/agent/projections.js.map

@@ -1 +1 @@
-{"version":3,"file":"projections.js","sourceRoot":"","sources":["../../src/agent/projections.ts"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,OAAgB,EAAE,GAAW;IACzE,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,oBAAoB,CAA4B,CAAA;IAC5E,IAAI,WAAW,EAAE,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACxD,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAC9B,GAAY,EACZ,OAAgB,EAChB,GAAW;IAEX,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,CAAA;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAgC,CAAC,CAAC,CAAC,SAAS,CAAA;AACnG,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,GAAY,EAAE,OAAgB,EAAE,GAAW;IAC1E,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,CAAA;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACtE,CAAC"}
+{"version":3,"file":"projections.js","sourceRoot":"","sources":["../../src/agent/projections.ts"],"names":[],"mappings":"AAaA;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,OAAgB,EAAE,GAAW;IACxE,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG,CAAC,oBAAoB,CAA4B,CAAA;IAC5E,IAAI,WAAW,EAAE,OAAO,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAA;IACtE,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;QAC/C,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAA;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAA;IAChC,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY,EAAE,OAAgB,EAAE,GAAW;IACzE,MAAM,IAAI,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,CAAA;IAC9C,OAAO,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACvD,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,gBAAgB,CAC9B,GAAY,EACZ,OAAgB,EAChB,GAAW;IAEX,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,CAAA;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAgC,CAAC,CAAC,CAAC,SAAS,CAAA;AACnG,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,gBAAgB,CAAC,GAAY,EAAE,OAAgB,EAAE,GAAW;IAC1E,MAAM,KAAK,GAAG,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,CAAA;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AACtE,CAAC"}

package/lib/agent/prompt-history.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Global prompt history for the terminal surface.
+ *
+ * The file is deliberately project-agnostic: a reader who types the same prompt
+ * in two checkouts wants it offered in both, so nothing here records a working
+ * directory. It lives beside the reader's other harness preferences rather than
+ * inside the profile, because a profile is replaced on install and history is
+ * theirs to keep.
+ */
+/** Environment variable that overrides the harness home, matching the launcher. */
+export declare const DSH_HOME_ENV = "DSH_HOME";
+/** Directory name of the default harness home under the OS home. */
+export declare const DSH_HOME_DIR_NAME = ".dsh";
+/** File name the history is stored under, inside the harness home. */
+export declare const HISTORY_FILE_NAME = "prompt-history.json";
+/** Schema this build writes; a file that names another positive version is left alone. */
+export declare const HISTORY_SCHEMA_VERSION = 1;
+/** Entries kept when the reader configures nothing. */
+export declare const DEFAULT_MAX_ENTRIES = 2000;
+/** Largest cap a reader may ask for, so a typo cannot grow the file without bound. */
+export declare const MAX_ENTRIES_LIMIT = 20000;
+/** Why the store refuses to write, which is a reason the reader can act on. */
+export type HistoryBlockReason = 'corrupt_history' | 'unsupported_schema' | 'unreadable_history';
+/** One recorded prompt, newest first in the file. */
+export interface PromptEntry {
+    readonly text: string;
+    readonly updatedAt: string;
+    readonly useCount: number;
+}
+/** The persisted document, versioned so a future shape can be recognized. */
+export interface PromptHistoryFile {
+    readonly version: number;
+    readonly updatedAt: string;
+    readonly entries: readonly PromptEntry[];
+}
+/** A file read reduced to what a caller can act on. */
+export type ParsedHistoryFile = {
+    readonly kind: 'ready';
+    readonly file: PromptHistoryFile;
+} | {
+    readonly kind: 'blocked';
+    readonly reason: HistoryBlockReason;
+};
+/** The store the surface holds; mutations are fire-and-forget and serialized. */
+export interface PromptHistory {
+    /** Current entries, newest first; the array identity is stable per snapshot. */
+    entries(): readonly PromptEntry[];
+    /** Persist one submitted prompt; blank input is ignored. */
+    record(text: string): void;
+    /** Remove every entry and report how many went. */
+    clear(): Promise<number>;
+    /** Resolve once every queued mutation has settled; errors are reported, not thrown. */
+    flush(): Promise<void>;
+    /** Absolute path of the file, for a status line and diagnostics. */
+    path(): string;
+    /** Why writes are refused, or undefined while the store is healthy. */
+    blockedReason(): HistoryBlockReason | undefined;
+}
+/** Inputs the surface supplies; every one is a seam a test drives. */
+export interface PromptHistoryOptions {
+    /** Resolved harness home; defaults to $DSH_HOME or ~/.dsh. */
+    readonly home?: string;
+    /** Read per mutation so a settings edit takes effect without a restart. */
+    readonly cap: () => number;
+    readonly now?: () => Date;
+    readonly warn?: (message: string) => void;
+    /** Lock wait a test can shorten; defaults to LOCK_WAIT_MS. */
+    readonly lockWaitMs?: number;
+}
+/**
+ * Resolve the harness home.
+ *
+ * Precedence is the launcher's own: $DSH_HOME, then ~/.dsh. A blank override is
+ * treated as unset, because resolving to the working directory would scatter
+ * private history into whatever tree the reader happened to start from.
+ */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv): string;
+/** Read one persisted document, refusing anything this build cannot safely rewrite. */
+export declare function parseHistoryFile(text: string): ParsedHistoryFile;
+/**
+ * Put one prompt at the front, replacing an exact duplicate.
+ *
+ * A duplicate is moved rather than copied so a repeated prompt resurfaces as the
+ * newest suggestion without ever appearing twice in the list.
+ */
+export declare function upsertEntry(entries: readonly PromptEntry[], text: string, now: string, maxEntries: number): PromptEntry[];
+/** Build the store the surface records into and completes from. */
+export declare function createPromptHistory(options: PromptHistoryOptions): PromptHistory;
+//# sourceMappingURL=prompt-history.d.ts.map

package/lib/agent/prompt-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-history.d.ts","sourceRoot":"","sources":["../../src/agent/prompt-history.ts"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AAEH,mFAAmF;AACnF,eAAO,MAAM,YAAY,aAAa,CAAA;AACtC,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,SAAS,CAAA;AACvC,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,wBAAwB,CAAA;AACtD,0FAA0F;AAC1F,eAAO,MAAM,sBAAsB,IAAI,CAAA;AACvC,uDAAuD;AACvD,eAAO,MAAM,mBAAmB,OAAO,CAAA;AACvC,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,QAAS,CAAA;AAmBvC,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG,oBAAoB,GAAG,oBAAoB,CAAA;AAShG,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;CACzC;AAED,uDAAuD;AACvD,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,CAAA;AAErE,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,gFAAgF;IAChF,OAAO,IAAI,SAAS,WAAW,EAAE,CAAA;IACjC,4DAA4D;IAC5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,mDAAmD;IACnD,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IACxB,uFAAuF;IACvF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,oEAAoE;IACpE,IAAI,IAAI,MAAM,CAAA;IACd,uEAAuE;IACvE,aAAa,IAAI,kBAAkB,GAAG,SAAS,CAAA;CAChD;AAED,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAuJD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAM3E;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAiBhE;AAuBD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,WAAW,EAAE,CAMf;AAMD,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAsGhF"}