From 126d5b2e55dca93e024f5654fed6fae37a012369 Mon Sep 17 00:00:00 2001
From: salmonik <salmonik@tuta.io>
Date: Mon, 17 Aug 2026 19:56:24 +0200
Subject: Terminal-app design (ADR 0005) + disk-write controller

- ADR 0005: persistent home terminal (full-screen, chrome-less,
  bottom-pinned), F1 terminal windows, per-instance vt/tty/shell,
  queue-based input for all terminals, and the disk controller
- Glossary: add the Terminal term; update Task/App for the new model
- Add a re-entrant disk lock (DiskGuard over the preemption-depth
  counter) and wrap all fs/fat mutating operations per-call
---
 docs/adr/0004-windowed-gui-and-compositor.md       |  4 +-
 ...0005-persistent-terminal-and-disk-controller.md | 48 ++++++++++++++++++++++
 2 files changed, 50 insertions(+), 2 deletions(-)
 create mode 100644 docs/adr/0005-persistent-terminal-and-disk-controller.md

(limited to 'docs')

diff --git a/docs/adr/0004-windowed-gui-and-compositor.md b/docs/adr/0004-windowed-gui-and-compositor.md
index 3476fab..87f637e 100644
--- a/docs/adr/0004-windowed-gui-and-compositor.md
+++ b/docs/adr/0004-windowed-gui-and-compositor.md
@@ -74,5 +74,5 @@ Introduce an overlapping-window GUI:
 - The existing `vt` dirty-cell path is demoted to a per-terminal-window
   trigger; the window manager becomes the only writer of the framebuffer
   (plus the cursor overlay).
-- Open (not yet decided): the terminal-app design (per-instance vt + shell),
-  and the save/image-format + image-viewer design (both deferred).
+- Open (not yet decided): the save/image-format + image-viewer design
+  (deferred).  The terminal-app design is captured in ADR 0005.
diff --git a/docs/adr/0005-persistent-terminal-and-disk-controller.md b/docs/adr/0005-persistent-terminal-and-disk-controller.md
new file mode 100644
index 0000000..dee62d1
--- /dev/null
+++ b/docs/adr/0005-persistent-terminal-and-disk-controller.md
@@ -0,0 +1,48 @@
+# ADR 0005 — Persistent terminal program, per-instance shell/vt, and a disk-write controller
+
+## Status
+
+Accepted.
+
+## Context
+
+The GUI (ADR 0004) left the console as a special "layer 0" rendered
+straight into the shared shadow, with a single shell (task 0) reading a
+global keyboard buffer and being the only thing that touches the disk.  We
+want a TempleOS-inspired **persistent terminal program**: a full-screen,
+always-present command line, plus the ability to spawn additional terminal
+windows.
+
+## Decision
+
+- **Home terminal** — a real window (own pixel buffer, composited by the
+  WM) that is full-screen, chrome-less (no title bar / minimize / close),
+  bottom-pinned (never raised), and never closes.  It is the persistent
+  desktop.
+- **F1 terminals** — ordinary windows (640×400, title bar, movable,
+  closable via F4 and the close button) running additional shell instances.
+- **Per-instance** — `vt` becomes a per-instance `Terminal` (cell grid,
+  cursor, ANSI parser, scroll); `tty` and `shell` become per-instance too.
+  Each terminal owns one of each.
+- **Input** — every terminal's shell reads `TaskMsg::Key` from its own task
+  queue (routed by the WM's input pump to the focused window).  No terminal
+  reads the global keyboard buffer; there is one input path for all.
+- **Rendering** — a terminal renders its text grid into its window's pixel
+  buffer; the WM composites it like any other window.  This supersedes the
+  scroll-hook workaround from ADR 0004.
+- **Disk controller** — `fs`/`fat` remain the disk owner, but every
+  mutating operation is wrapped in a re-entrant preemption-disable lock,
+  serializing concurrent access from multiple shells.  Per-call granularity.
+- **Background** — a terminal's running command keeps producing output into
+  its buffer while unfocused (free from preemptive multitasking plus
+  per-terminal buffers).
+
+## Consequences
+
+- Positive: the console is a first-class program; multiple terminals share
+  one coherent input path; concurrent disk access is safe.
+- Negative: the preemption-disable disk lock stalls the scheduler during
+  disk I/O (fine on QEMU's RAM-backed disk; revisit for real hardware).
+- Negative: a substantial refactor of `vt`/`tty`/`shell` from globals to
+  instances.
+- The "only the shell touches the disk" assumption is removed.
-- 
cgit v1.2.3