From 27816a707a1b4294fe5360f65fdd5e5fe1e84b9d Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 24 Aug 2026 22:10:04 +0200 Subject: [PATCH] docs: plan terminal output notifications Assistant: codex Assistant-Model: gpt-5.6-sol Assistant-Session: 01a03397-4d51-7fd1-8ff2-946eb22ea2bc --- WORK-RECORDS.md | 6 + ...Q-WP-0007-terminal-output-notifications.md | 109 ++++++++++++++++++ 2 files changed, 115 insertions(+) create mode 100644 workplans/TAMQ-WP-0007-terminal-output-notifications.md diff --git a/WORK-RECORDS.md b/WORK-RECORDS.md index dd61c9b..3a99fc8 100644 --- a/WORK-RECORDS.md +++ b/WORK-RECORDS.md @@ -15,6 +15,7 @@ | workplan | TAMQ-WP-0004 | finished | — | workplans/TAMQ-WP-0004-operator-installable-local-alpha.md | | workplan | TAMQ-WP-0005 | finished | — | workplans/TAMQ-WP-0005-terminal-neutral-manual-messaging.md | | workplan | TAMQ-WP-0006 | finished | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md | +| workplan | TAMQ-WP-0007 | active | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md | | task | TAMQ-WP-ADHOC-2026-08-24-T01 | done | — | workplans/ADHOC-2026-08-24.md | | task | TAMQ-WP-0001-T01 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md | | task | TAMQ-WP-0001-T02 | done | — | workplans/TAMQ-WP-0001-statehub-bootstrap.md | @@ -40,3 +41,8 @@ | task | TAMQ-WP-0006-T03 | done | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md | | task | TAMQ-WP-0006-T04 | done | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md | | task | TAMQ-WP-0006-T05 | done | — | workplans/TAMQ-WP-0006-shell-native-message-routing.md | +| task | TAMQ-WP-0007-T01 | progress | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md | +| task | TAMQ-WP-0007-T02 | todo | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md | +| task | TAMQ-WP-0007-T03 | todo | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md | +| task | TAMQ-WP-0007-T04 | todo | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md | +| task | TAMQ-WP-0007-T05 | todo | — | workplans/TAMQ-WP-0007-terminal-output-notifications.md | diff --git a/workplans/TAMQ-WP-0007-terminal-output-notifications.md b/workplans/TAMQ-WP-0007-terminal-output-notifications.md new file mode 100644 index 0000000..27a0dc3 --- /dev/null +++ b/workplans/TAMQ-WP-0007-terminal-output-notifications.md @@ -0,0 +1,109 @@ +--- +id: TAMQ-WP-0007 +type: workplan +title: "Target-pane terminal output notifications" +domain: communication +repo: tmux-amq +status: active +owner: codex +topic_slug: coulomb-social +planning_priority: P0 +planning_order: 12 +created: "2026-08-24" +updated: "2026-08-24" +--- + +# Target-pane terminal output notifications + +Make a durably routed message visibly appear in its target repository terminal +without turning any bytes into input for the pane occupant. + +## Required operator contract + +```bash +tamq flex-auth audit-core +# in flex-auth +@audit-core: Some message! +``` + +The `audit-core` pane receives terminal output equivalent to: + +```text +#flex-auth: Some message! [m-...] +``` + +Tamq resolves the target pane's pseudo-terminal through tmux and writes a +sanitized notification to that device's output queue. It never uses +`send-keys`, never sends Enter, and never alters the foreground process's stdin. +The notification may visually interleave with a prompt or be redrawn by a +full-screen program; the durable inbox remains authoritative. + +Messages remain pending after display until `tamq ack` or a successful explicit +inbox filter. A persisted display timestamp prevents successful notifications +from being emitted repeatedly after broker polls or restarts. + +## Specify and isolate the output channel + +```task +id: TAMQ-WP-0007-T01 +status: progress +priority: high +``` + +Define terminal-output delivery separately from legacy pane-input injection. +Resolve only tmux-reported `/dev/pts/` character devices owned by the +current user, sanitize terminal control bytes, use bounded non-blocking writes, +and document visual interleaving as a display limitation rather than an input +safety failure. + +## Persist one-time display state + +```task +id: TAMQ-WP-0007-T02 +status: todo +priority: high +``` + +Add a migration-safe `displayed_at` marker. Claim a pending message before +output, record successful display and release its lease atomically, retain its +pending acknowledgement state, and make broker restart/poll behavior +idempotent after a successful write. + +## Make terminal output the normal managed-session mode + +```task +id: TAMQ-WP-0007-T03 +status: todo +priority: high +``` + +Register ordinary started sessions in `output` mode and advertise the required +broker capability. Preserve `--tap --command` as explicit pane-input mode, +provide `--no-display` for durable inbox-only operation, and restart an older +broker before registering the new mode. + +## Prove output without input + +```task +id: TAMQ-WP-0007-T04 +status: todo +priority: high +``` + +Use a real pseudo-terminal and real tmux acceptance to prove the notification +appears in pane output, never reaches foreground-process stdin, remains pending +for acknowledgement, emits only once across polls, handles multiline/control +content safely, retries failed output, and retains manual and explicit tap +modes. + +## Install and document the operator workflow + +```task +id: TAMQ-WP-0007-T05 +status: todo +priority: high +``` + +Update help, README, SCOPE, and installed-package acceptance. Install the +verified build, recreate or re-register a live two-repository session, exchange +and acknowledge one visible smoke message, and record State Hub evidence.